

                              ###      #####      ## 
                               ##     ##   ##     ## 
                        ####   ##         ##      ## 
                       ##      #####    ###    ##### 
                        ####   ##  ##  ###    ##  ## 
                           ##  ##  ## ##   ## ##  ## 
                        ####   ##  ## #######  ### ##
         
                              [ sh2d  Readme ]
                             Bart Trzynadlowski


This is the documentation for sh2d Version 0.2, please read it. sh2d is public
domain software, thus I claim absolutely no responsibility for it.
        Feedback is appreciated. Please read this documentation first before
contacting me. You can email me at the following address: trzy@powernet.net.


[ About ]

sh2d is a disassembler for Hitachi SH-1 and SH-2 code. Although the method
used to decode instructions isn't very efficient, disassemblers aren't speed-
critical applications and sh2d performs more than well enough.
        I wrote sh2d to get acquainted with the SH-1 and SH-2 processors and
because I found that sddis and shdis were inadequate for my needs. Hopefully
sh2d can satisfy your needs as well. 


[ Usage ]

Simply specify the file you wish to disassemble on the command line and you're
set. sh2d prints source lines using the following format:

        Address     Data        Instruction & Operand(s)        Physical
        0x00000006: 0xC742      mova    @(0x10C, pc), r0        ; 0x00000110

The address is simply the PC position of the current instruction. The data is
how the instruction is encoded, and the "instruction & operand(s)" field is
the disassembled instruction with any operands it may have. Instructions with
the PC-relative addressing mode will have a "physical" field which is the
physical address that the PC and displacement signify. 
        By default, sh2d uses the SH-2 mode. If you wish to disassemble for
SH-1 code, you will probably want to specify the -sh1 option on the command
line. This will make all SH-2 specific instructions appear as unrecognized.
        sh2d also allows you to specify where you want to start disassembling
and how many bytes to disassemble. The starting position is specified by the
-s option. Type the hexadecimal offset at which to start after the -s. Do not
use 0x, h, H', or $ indicators.
        The -l option specifies the length of the disassembly in bytes. Type
a base 10 number after the -l. Odd numbers will be rounded up to the next
integer. Without using -s or -l, sh2d starts at offset 0 and disassembles the
entire file.
        An origin option is provided, -o, specify the origin in hexadecimal.
Example: A starting point of 0 and an origin of 100 will disassemble the word
at 0x00000000 but will print it as address 0x00000100.

For a list of options, just type sh2d without anything else on the command
line for the help text; you can also use -? or -h.
        It is important to note that sh2d writes to stdout, so input can be
redirected to a file or another program. Error messages go to stderr.

A Win32 console version of sh2d has also been provided, sh2d32.exe. It was
built with Microsoft VisualC++ 6. It works exactly like sh2d except that it
can only be used while Windows is running.

There are still some things that may be incorrect, please report any problems
to me ASAP and I'll try to get them fixed.

   
[ Compiling and Advanced Usage ]   

Any C compiler should handle sh2d.c just fine, but a good 32-bit compiler is
recommended. gcc is ideal and will produce code that can load large file sizes
but TurboC++ on the other hand produces an executable that can't even load a
500K file.
        The SH2Disasm() function does most of the work. It is quite simple to
read and can be used in other projects if you need an integrated SH-1/SH-2
disassembler in your program. Just copy the i_descr struct, the tab[] table,
and the SH2Disasm() function and paste it in your code.


[ Change History ]

Version 0.2: July 24, 2000
                - Fixed an address-decoding bug with the "mova" instruction

Version 0.1: July 12, 2000
                - Fixed a bug causing "mac.w @rm+, @rn+" to be interpreted as
                  "mac.l @rm+, @rn+"

Version 0.0: June 11, 2000
                - Initial release


[ Etc. ]

Bug reports are welcome, send them to me, trzy@powernet.net, as soon as you
find any. Special thanks to David Midnight, Charles Doty, Shawn L. Baird, and
Tim Meekins for their help.
