Frozen Fish 1: Amiga/FrozenFish-Apr94.iso/bbs/alib/d5xx/d555/thea64package.lha/TheA64Package/A64Utils.lzh/Doc/Converter

Text File | 1991-10-02 | 28KB | 694 lines

CONVERTER

    Included with The A64 Package are two utilities "Optimize" and
    "Convert."  These utilities are designed to make A64 run C64
    programs faster.  The speed increases gained with these utilities
    can range from slightly faster than normal to too fast to use and
    the average result will be A64 running twice as fast as normal.
    Both of these utilities work with map dump files created with
    A64.  It is suggested that you familiarize yourself with this
    feature of A64 before continuing (See LOAD MAP and SAVE MAP in
    THE CODE MENU section).


A64's SPEED

    A64 is written entirely in assembly language so that it can run
    C64 programs at the fastest possible speed, but even with the
    Amiga running 7 times faster than the C64, A64 sometimes has
    trouble doing everything it has to at 100% speed.  Sometimes this
    slow down will be barely noticeable and other times it will be
    painfully apparent.  There are many things that can be done to
    make C64 programs run faster, by reading through the A64 Prefs
    section of the manual you will notice that many Prefs settings
    effect A64's speed, usually the speed increase gained with each
    setting is small, but when all of the settings are set to their
    optimum settings the total speed increase can be great.  Even
    with all of the Prefs settings A64 may still not run some C64
    programs fast enough, so we developed two utilities to help make
    A64 run faster, "Optimize" and "Convert."


OPTIMIZE

    Believe it or not, many C64 programs spend a great deal of time
    sitting in loops doing absolutely nothing, but wasting time.
    This is done to keep C64 programs from performing some operations
    too fast.  For example, if the C64 were to move a sprite across
    the screen as fast as it was able the sprite would become a blur.
    So programmers put delay loops in their programs to slow things
    down.  For example, moving the sprite again, the program would
    work like this: move the sprite, wait, move the sprite, wait...
    As you can tell this process of waiting wastes a great deal of
    time.  The Optimize utility allows you to remove many of these
    waits from a C64 Program.

    The Optimize utility must be run from the Shell and its usage is
    as follows:

        Optimize <source map> [dest map]




                                                                 4-1









        <source map> is a required parameter, it is the name of the
                     map dump file that you want to optimize.
        [dest map]   is an optional parameter, it is the name of the
                     file that you want Optimize to write the
                     optimized map dump to.  If this parameter is not
                     specified Optimize will overwrite <source map>
                     with the optimized map dump.

    The Optimize utility will load the specified map dump file and
    search it for delay loops.  When Optimize finds a delay loop, the
    delay loop will be displayed as a disassembly listing and you
    will be asked if Optimize should remove the delay.  Enter Y for
    yes, remove the delay or N for no, don't remove the delay.  After
    Optimize is done it will save the new map dump with the name you
    specified.  You can then load the optimized map dump file with
    A64 Prefs' LOAD MAP feature.

    The reason you are asked if the delay should be removed is that
    there may be times when you don't want to remove all of the
    delays in a C64 program.  Removing some delays can cause some C64
    programs to run too fast.  If you encounter this problem you'll
    have to experiment with removing some delays and not others until
    you find the one(s) that are making A64 run too fast.  This is
    not hard to do, because most C64 programs that use delays usually
    don't use more than four or five of them.  Because you may have
    to run Optimize on a map dump file several times, it is suggested
    that you specify a [dest map] until you get the C64 program
    running acceptably.

    NOTE: We have barely scratched the surface in realizing
          Optimize's full potential for speeding up C64 programs.
          In future versions we can expect many more speed
          increases with a greater range of programs.


HOW A64 RUNS A PROGRAM

    To A64, all Commodore 64 programs are actually machine language
    programs.  Even a BASIC program can be considered to be machine
    language, because A64 doesn't actually run the BASIC code, it
    instead runs the C64's BASIC ROM which in turn runs the BASIC
    program and the BASIC ROM is machine language.

    Machine language programs are made up of opcodes.  Opcodes are
    machine language instructions that tell the computer to perform
    some tiny operation, like move a value from one place to another
    or perform some kind of operation to a value.  It takes many,
    many opcodes to perform even the simplest operations on your
    computer.

    The opcodes of a machine language program are executed by the


                                                                 4-2









    computer's microprocessor.  The Amiga and the C64 use different
    microprocessors so their machine languages are different.  This
    is one of the reasons why you usually can't take a program
    written for one computer and run it on a different computer.

    Because the Amiga uses a different microprocessor than the C64,
    the Amiga can not directly run a C64's machine language.  To
    run a C64 machine language program on the Amiga, the program must
    be interpreted.  Meaning a Amiga program must fetch each C64
    machine language opcode and then execute a set of instructions
    that simulate the operations of the C64's opcode.  This is how
    A64 runs a C64 program, it continuously fetches and simulates
    C64 opcodes.  As you might imagine, this process of interpreting
    the C64's opcodes is very time consuming.  A64 must be able to
    interpret thousands of C64 opcodes per second and still handle
    graphics, I/O and other miscellaneous functions.


CONVERT

    The Convert utility allows you to convert the C64 machine
    language stored in a map dump file into Amiga machine language.
    This conversion process eliminates a great deal of work that A64
    would normally have to do "on the fly."  A64 will no longer have
    to interpret the C64 machine language because it will already be
    in a form that A64 understands, pure Amiga machine language.
    This conversion process will result in A64 running a C64 program
    anywhere from 2 to 5 times faster than it normally would.

    NOTE: The Convert utility is fairly complex and it is geared
          toward the more experienced C64 user.  To use the Convert
          utility it is recommended that you have at least a basic
          understanding of 6510 machine language and of the C64's
          architecture.

    To explain how to use the Convert utility we will show its usage
    and then explain each parameter.  The Convert utility must be run
    from the Shell and its usage is as follows:

        Convert <MapDump> [-OOutput] [-AAddr file] [-L] [-Bxxx] [-P]

MAPDUMP PARAMETER

    The <MapDump> parameter is required, it is the name of the map
    dump file that you want Convert to use for the conversion.

OUPUT PARAMETER

    The [-OOutput] parameter is optional, it is the name of the file
    that you want Convert to write the converted code to.  If this
    parameter is not specified then Convert will output the converted


                                                                 4-3









    code to the file <MapDump>.conv.  This output file is the file
    that can be loaded with A64 Prefs LOAD CODE menu option.

ADDR FILE PARAMETER

    The [-AAddr file] parameter is optional, it is the name of the
    address file that Convert will use to aid it in the conversion
    process.  If this parameter is not specified then Convert will
    assume that the address file is named <MapDump>.addr.

    The address file is the key to how Convert works.  The C64 memory
    map contains 64k of RAM.  This RAM is addressed at $0000 - $FFFF.
    Whenever the C64 loads a program it stores the program somewhere
    in this 64k of RAM, but very few programs use the entire 64k for
    storing actual program code.  Convert uses the address file to
    determine what sections of the 64k RAM it should convert and what
    sections it should ignore.  You must create an address file for
    every program that you wish to convert.  If you have a basic
    understanding of 6510 machine language creating address files is
    relatively simple.

WHAT IS AN ADDRESS FILE

    Address files are simple text files that you must create
    yourself.  They can be made with any text editor or word
    processor that can save files in pure ASCII.  Like its name
    implies address files are files that contain addresses.  These
    addresses are used by Convert to determine what it should and
    should not convert.  These addresses can be broken down into
    two catagories: addresses to include in the conversion and
    addresses to exclude from the conversion.

    Here is an example of part of an actual address file:

        ; Address file for H.E.R.O.

        #$8000-$8fff       ; <- these are the addresses to include
        #$9000-$9fff

        !$8000-$8008       ; <- these are the addresses to exclude
        !$81ff-$8206

    The first thing you must specify in an address files is what
    addresses Convert must include in the conversion process.
    Addresses to be included begin with the # symbol and specify the
    start and end address of the section of the C64 memory map to be
    included.  Because of the way that Convert actually converts the
    C64 code your include addresses should always start on even 4k
    boundaries and be 4k in size, this is not absolutely required,
    but is strongly recommended.



                                                                 4-4









    Include addresses must be specified in address order and can be
    listed in either hexadecimal or decimal.  Addresses are assumed
    to be decimal unless they begin with the $ symbol.

    After all the include addresses are specified you then must
    specify what addresses within the included sections to exclude.
    Addresses to be excluded begin with the ! symbol and specify the
    start and end address of the section of the C64 memory map to be
    excluded.  These addresses are always within an included area.
    There are three instances where you would want to exclude
    addresses from the included sections:

        1. The C64 program has data imbedded in its code.
        2. The C64 program is using undefined opcodes.
        3. The C64 program is using self-modifying code.

    Exclude addresses must be specified in address order and can be
    listed in either hexadecimal or decimal.  Addresses are assumed
    to be decimal unless they begin with the $ symbol.

    Creating address files is not as complex as it may appear, by
    using A64Mon and the List option in Convert (discussed below)
    finding the addresses to put in the address file is simple.  For
    a step by step example of converting a C64 program and creating
    an address file see CONVERTING A C64 PROGRAM.

THE -L PARAMETER

    The -L parameter is optional, it is used to create listing files
    that help in the conversion process of a C64 program.  When you
    specify the -L option Convert will generate a listing file for
    each included section listed in the address file.  A listing file
    contains a disassembly of the included section with some comments
    that help determine what areas of an included area should be
    excluded.  As already stated, Convert creates a listing file for
    each included section, these listing files can be very large and
    if you specify a very large area of the memory map to be included
    as one chunk you could generate a file that is too large to be
    read.  This is one of the reasons why it is recommended that when
    you specify areas to be included that they are no bigger than 4k.
    A listing file for a 4k section will be approximately 35k to 45k
    in size.  Also if you include the entire 64k in an address file
    the resulting listing file(s) could easily fill an 880k floppy.

THE -B PARAMETER

    The -B parameter is optional, it is used to tell Convert how much
    of the Amiga's memory to reserve for the conversion process.
    Converted code files can be very large, they average 40 to 50k
    per 4k section of the 64 memory map.  If you tried to convert the
    entire 64k map the resulting code file would be over 800k in


                                                                 4-5









    size!  luckily it is rare to even have to convert half of the
    memory map so code files of this size are not needed.  Convert
    normally allocates 50k per 4k included section which is more than
    sufficient for final converted code files, but during the initial
    conversion process you will likely get code buffer overflow
    errors until you start excluding addresses.  To get Convert to
    successfully go through the initial conversion process you may
    have to specify a larger than 50k block size.  The block size is
    specified by -Bxxx and xxx can be 24 to 128, which represents
    how many kilobytes of memory to set aside for each included 4k
    section.

THE -P PARAMETER

    Convert is capable of outputting code that is specifically
    generated for either the 68000 microprocessor or for the 68010,
    68020 or 68030 microprocessor.  The -P option is used to tell
    Convert that it should create the code for a microprocessor
    other than the 68000.  If your Amiga has a 68010, 68020 or 68030
    installed you must specify this option or A64 will not run the
    converted code module.  Likewise if you have a 68000 installed
    you should not specify the -P option or A64 will refuse to run
    the converted code.

CONVERTING A C64 PROGRAM

    We realize that the Convert utility appears to be very complex,
    but once you successfully convert a C64 program you'll see that
    it is not too difficult to do.  And once you see the speed
    increases that can be gained with converted code we're sure that
    you'll want to convert as many C64 programs as possible.

    We will help guide you through your first code conversion by
    listing step by step what you should do.  This example assumes
    that you are either using a floppy based system with an external
    drive and an A64 WorkBench as outlined in the GETTING STARTED
    section or that you are using a hard disk.  If you are using a
    floppy based system you should have a newly formatted blank disk
    ready.  If you are using a hard disk you may want to create a
    directory on your hard disk specifically for map dumps and
    converted code files.  A good example would be to create a
    directory named Maps in TheA64Package directory.  For this
    example we will be using the C64 program Archon.  If you do not
    have Archon you should still be able to follow this example using
    some other program.

    The first thing we must do is create a map dump file for the
    program we wish to convert.  Run A64 and then load the C64
    program to be saved.  When the C64 program is done with all
    loading enter A64 Prefs.  Select SAVE MAP in the CODE MENU.
    Save the map dump file with the name Archon.map (assuming you


                                                                 4-6









    are using Archon) to either the blank formatted disk or to
    the directory on your hard disk.  Now that we have a map dump
    file we are ready to start the conversion process.

    Located in the A64Utilities drawer of The A64 Package is a
    complete address file for Archon called Archon.addr.  You should
    copy this file to where you saved the map dump file.  By using
    the map dump file and this address file you can now create a
    converted code file for Archon by typing the following:

        cd <directory>
        Convert Archon.map

    When Convert is done you can then load the outputted file
    Archon.conv with the A64 Prefs' LOAD CODE feature, but this does
    not show you how to create your own address files.

    We will now explain how and why the Archon.addr file contains the
    addresses it does and how to make your own address files.

    Using a text editor or word processor (you can use NotePad on your
    WorkBench) open the Archon.addr file.  Here is a partial listing
    of the address file.

        ; Address file for Archon

        #$6000-$6fff       ; <- These are the addresses to include
        #$7000-$7fff       ;    Notice that the include addresses
        #$8000-$8fff       ;    always start on a 4k boundary and are
        #$9000-$9fff       ;    always 4k in size
        #$a000-$afff
        #$c000-$cfff

        !$6000-$60ff       ; <- These are the addresses to exclude
        !$6323-$632c       ;    Notice how the exclude addresses are
        !$67a0-$67b6       ;    always within an included block
        !$6a4f-$6afd
        !$6d27-$6d37

    The first thing to do when creating an address file is to
    determine where in the memory map the C64 program is and then
    to specify these addresses to be included in the conversion.
    Convert always works with 4k blocks of the memory map so the
    include addresses will always be a combination of up to 16
    possible blocks (4k x 16 = 64k).  The 16 possible 4k blocks that
    can be included are:

        $0000-$0fff     $1000-$1fff     $2000-$2fff     $3000-$3fff
        $4000-$4fff     $5000-$5fff     $6000-$6fff     $7000-$7fff
        $8000-$8fff     $9000-$9fff     $a000-$afff     $b000-$bfff
        $c000-$cfff     $d000-$dfff     $e000-$efff     $f000-$ffff


                                                                 4-7









    It is very simple to determine what 4k blocks to include by using
    A64Mon.  The goal is to try and eliminate as many as the 4k
    blocks as possible.  The first thing to do is determine how the
    C64's memory map is configured.  This is done with the MemCntrl
    command in A64Mon.  When using this command with Archon loaded we
    can tell that Archon leaves the Kernal ROM switched in so we can
    eliminate the 4k blocks at $e000-$efff and $f000-$ffff.  If
    Archon had also switched out BASIC we could have eliminated the
    4k blocks at $a000-$afff and $b000-$bfff.  The next thing to do
    is search through the remaining blocks with the Disasm command in
    A64Mon.  Start disassembling at the start of each 4k block.  It
    is usually not necessary to disassemble the entire 4k block
    before you can determine if the block should be included or
    excluded.  If you see many undefined opcodes (undefined opcodes
    are shown by ???) or large sections that contain the same opcode,
    for example many BRKs, then the block can be excluded.  Don't
    worry if you exclude some code or include some data, Convert is
    very flexible.  The goal is to include as much code as possible.
    There are other A64Mon commands that can also be useful for
    finding what blocks to include and exclude.  The IntVec command
    can be used to determine where a program's interrupts are
    located.  Interrupts code should be included whenever possible.
    As we can see Archon's IRQs are at $637e so the $6000-$6fff block
    should definitely be included.  Archon NMIs are in the Kernal ROM
    so they can be ignored.  Another command that can be useful is
    VICDump command.  The VICDump command will tell us what graphics
    bank a C64 program is using.  The C64 is capable of storing
    graphics data in one of four possible 16k banks.  These 16k banks
    are: bank 0 at $0000-$3fff, bank 1 at $4000-$7fff, bank 2 at
    $8000-$bfff and bank 3 at $c000-$ffff.  A C64 program is less
    likely to use the graphics bank area to store code because it
    needs the memory for graphics data, but this is not always the
    case as we can see in Archon, which uses graphics bank 1 and
    stores code in the second half of it.

    When you are done determining what 4k blocks to include you are
    ready to start converting the code.  The next thing to do is
    determine what sections within the included areas should not be
    converted.  The way this is done is run Convert on the map dump
    file using just the include addresses in the address file and
    specifying the -L option.  For the following example you should
    comment out all of the exclude addresses in the Archon address
    file.  To comment a line in an address file insert a ; at the
    start of the line.  When you are done you should now have an
    address file that only specifies addresses to include.  Now run
    Convert as follows:

        Convert Archon.map -L -B60

    The conversion process will now be slower than last time because
    Convert will now create a listing file for each included 4k


                                                                 4-8









    block.  When Convert is done it will print how many warnings
    and errors occurred during the conversion.  You should have 1462
    warnings and 0 errors.  Convert will also say that the conversion
    was successful.  As long as there are no errors then the
    converted code can be loaded with the LOAD CODE menu option in
    A64 Prefs, but as long as there are warnings the possibility
    exists for A64 to experience problems running the converted code.
    The goal is to get Convert to convert the program with 0 warnings
    and 0 errors.  The way to get rid of the warnings is to make
    Convert exclude the addresses that are creating the warnings.

    In each listing file created by Convert is a disassembly of a an
    included block.  Also listed in these files will be any warnings
    that occurred during the conversion.  There are two types of
    warnings that can appear in the listing files.  The first type of
    warning signifies that Convert found either data or an undefined
    opcode in the included section.  This type of warning will appear
    in the listing files like this:

    WARNING: Undefined opcode or data $xx at PC $xxxx.

    This type of warning is the more common of the two types and will
    not create problems if the address that is listed is not
    excluded, but will result in the converted code being much bigger
    than it has to be.  In the case of Archon the converted code is
    243k with all the warnings removed and is 326k without the
    warnings removed, a difference of 83k.  For this reason it is
    recommended that you exclude the addresses listed in these
    warnings.

    The second type of warning signifies that Convert found that the
    C64 program is using self-modifying code.  This type of warning
    will appear in the listing files like this:

    WARNING: Program writing to converted code at PC $xxxx to $xxxx.

    This type of warning can create problems for A64 if the second
    address listed is not excluded.  Converted code can not handle
    self-modifying code and the second address listed should be
    excluded.  Failing to exclude this address should not cause A64
    to crash when the converted code is run, but may result in A64
    not running the C64 program correctly.

    Now that we know what the warnings are, lets remove them.  Using
    a text editor or word processor open the first listing file named
    Archon.6000-6FFF.list.  Right away we can see many undefined
    opcode or data warnings.  By looking at the start of the listing
    file we can see that this block does not start with valid 6510
    code and by searching through the file we can see that actual
    code does not start until $6100.  So we have our first exclude
    line for our address file: !$6000-$60ff.  This is how we get rid


                                                                 4-9









    of the undefined opcode or data warning, by excluding the
    addresses where the warning occurred.  The second type of warning
    has to be removed differently.  Now open of the last listing file
    Archon.C000-CFFF.list.  If you search down in the file to PC
    $C0CD you will see an instance of the second type of warning that
    looks like this:

    WARNING: Program writing to converted code at PC $C0CD to $C561.

    To get rid of the problem that this warning signifies we have to
    exclude the second address $C561, not the first address $C0CD.
    If you search down in the file some more to PC $C561 you'll see
    a line like this:

    C561 01 20    ORA ($20,X)

    This is the line that has to be excluded, the addresses $6561-
    $6562 happen to fall at the end of some data so the whole section
    can be excluded with the line: !$c53b-$c562.

    Its as simple as that.  Just search each listing file for all the
    warnings and exclude the addresses shown in the warnings.  It
    helps to have some prior knowledge of 6510 assembly language, but
    by looking at the address file for Archon and by looking at the
    warnings in the listing files you should get a good idea of what
    should be excluded.  Remember, Convert is very flexible.  If you
    exclude more than you should, it is ok.

    NOTE: You can also use the Optimize utility in conjunction with
          Convert for even greater speed increases.  You should run
          Optimize on the map dump file before starting the
          conversion process.


WHAT CAN AND CAN'T BE CONVERTED

    Almost any C64 machine language program can be converted, but
    there are two things to be aware of.  Programs that use multiple
    loads should be converted with caution.  If a program loads
    different code over an area that you have previously converted we
    can guarantee that you will have problems running the C64
    program.  Also, Convert can not catch all instances of
    self-modifying code.  If the self-modifying is done using one of
    the 6510's indirect addressing modes Convert can not catch it.
    This problem is very hard to find and correct.  If you find a
    C64 program that runs fine under A64, but when converted it fails
    to run correctly there is a good chance that you have included
    some code that is being self-modified.  To correct the problem
    you'll either have to try to track down the self-modifying code
    be examining the listing files or experiment with not including
    some blocks until you eliminate the problem.


                                                                 4-10









    BASIC programs can not be converted.

NOTE TO CONVERTERS

    We realize that Convert is not for everyone.  We hope that the
    people who are able to use Convert will make their address files
    available in the PD so everyone can benefit.  If you have
    created some address files send them to us.  We will do our best
    to provide as many address files as possible to all users of The
    A64 Package.











































                                                                 4-11