README
vPICdisasm - Version 1.3 - 04/03/2011
Vanya A. Sergeev - <vsergeev@gmail.com>
================================================================================
Table of Contents

1. ABOUT vPICdisasm
2. LICENSE
3. COMPILING vPICdisasm
4. USAGE
5. USING vPICdisasm
6. Ghetto Address Labels
7. Shortcomings
8. Source Code
9. Sample Disassembly Outputs
================================================================================

1. ABOUT vPICdisasm
================================================================================
vPICdisasm is a Microchip PIC firmware disassembler that supports the Baseline,
Mid-Range, and Mid-Range Enhanced 8-bit PIC cores. This single-pass disassembler
can read Intel HEX8 and Motorola S-Record formatted files containing valid PIC
program binaries.

vPICdisasm fully supports all 35 Mid-Range PIC instructions (as well as the two
deprecated ones: "option" and "tris"), the additional 21 Mid-Range Enhanced
PIC instructions, and the 33 Baseline PIC instructions.

vPICdisasm features a handful of formatting options, including:
 - Printing the instruction addresses alongside disassembly, enabled by default
 - Printing the destination address of relative branch/jump/call instructions
   as comments alongside disassembly, enabled by default
 - Printing the original opcode data alongside disassembly
 - Ghetto Address Labels (see "Ghetto Address Labels" section)
 - Literal operands represented in either hexadecimal, binary, or decimal bases,
   and as ASCII in an assembly comment
 - data word directive for data not recognized as an instruction during
   disassembly
 - Piped input and output

vPICdisasm should work on most *nix platforms, including a Cygwin or MinGW
environment. vPICdisasm was written by Vanya A. Sergeev, and tested with the
GNU C Compiler on Linux. Feel free to send any ideas or suggestions to vsergeev
at gmail dot com.

2. LICENSE
================================================================================
vPICdisasm is released under the GNU General Public License Version 2.
    You should have received a copy of the GNU General Public License
    along with this program; see the file "COPYING".  If not, visit
    http://www.gnu.org or write to the Free Software Foundation, Inc.,
    59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

3. COMPILING vPICdisasm
================================================================================
Simply by running,
$ make
 in the vPICdisasm project directory should compile vPICdisasm on most
*nix systems, including a Cygwin or MinGW environment. The Makefile is
configured to use GCC to compile vPICdisasm.

vPICdisasm should have no problem being compiled with "gmake".

4. USAGE
================================================================================

Usage: vpicdisasm <option(s)> <file>
 Disassembles PIC program file <file>. Use - for standard input.
 Written by Vanya A. Sergeev - <vsergeev@gmail.com>.

 Additional Options:
  -o, --out-file <output file>	Write to output file instead of standard output.
  -a, --arch <architecture>	Specify the 8-bit PIC architecture to use
				during disassembly.
  -t, --file-type <type>	Specify the file type of the object file.
  -l, --address-label <prefix> 	Create ghetto address labels with
				the specified label prefix.
  --original                    Print original opcode data alongside
				disassembly.
  --no-addresses		Do not display the address alongside
				disassembly.
  --no-destination-comments	Do not display the destination address
				comments of relative branch instructions.
  --literal-hex			Represent literals in hexadecimal (default)
  --literal-bin			Represent literals in binary
  --literal-dec			Represent literals in decimal
  --literal-ascii		Show ASCII value of literal operands in a
				comment
  -h, --help			Display this usage/help.
  -v, --version			Display the program's version.

Supported 8-bit PIC Architectures:
  Baseline 			baseline
  Mid-Range			midrange (default)
  Enhanced Mid-Range		enhanced

Supported file types:
  Intel HEX8 			ihex
  Motorola S-Record 		srecord


4. USING vPICdisasm
================================================================================

* File Input:
	For most purposes:
	 $ vpicdisasm <PIC program file>
	Example:
	 $ vpicdisasm sampleprogram.hex

	Use - for standard input.

	vPICdisasm will assume the Mid-Range PIC architecture by default. You can
	specifiy an alternate architecture with the -a or --architecture option.
	Example:
	$ vpicdisasm -a enhanced sampleprogram.hex

* Option -t or --file-type
	vPICdisasm will auto-recognize Intel HEX8, and Motorola S-Record files
	by their first character. However, the -t or --file-type option can be
	used to explicitly select the file format.
	Example:
	 $ vpicdisasm -t ihex sampleprogram

	The file type argument for this option can be "ihex", or "srecord" for
	Intel HEX8 or Motorola S-Record formatted files, respectively.

* Option -o or --out-file <output file>
	Specify an output file for writing instead of the standard output. The
	output file - is also synonymous for standard output.

* Option -a or --architecture
	vPICdisasm supports the Baseline, Mid-Range, and Mid-Range Enhanced
	8-bit PIC cores. The architecture can be specified with this option,
	followed by the architecture identifier (right side of the list below):
		Baseline		baseline
		Mid-Range		midrange (default)
		Mid-Range Enhanced	enhanced

* Option --original
	Print the original opcode data to the left of the disassembly.
	Note: this option is ignored if address labels are enabled (to ensure
	assemble-able code).

* Options --literal-hex, --literal-bin, --literal-dec
	vPICdisasm can represent literal operands in either hexadecimal,
	decimal, or binary bases. The base can be specified with the
	--literal-hex, --literal-bin, and --literal-dec options.

* Options --literal-ascii
	Display the ASCII value of a literal operand in an assembly comment.

* Options --no-addresses, --no-destination-comments
	By default, vPICdisasm will print the instruction addresses alongside
	disassembly and destination comments for relative branch, jump, and call
	instructions. These formatting options can be disabled with the
	--no-addresses and --no-destination-comments options, respectively.

* Options -l or --address-label
	See the "Ghetto Address Labels" section.

* Options -h or --help, -v or --version
	The -h or --help option will print a brief usage summary, including
	supported program options and file types.
	The -v or --version option will print the program's version number.

If you encounter any program bugs or problems, please notify the program
author by email: Vanya A. Sergeev - vsergeev at gmail dot com.

5. Ghetto Address Labels
================================================================================
vPICdisasm supports a unique formatting feature: Ghetto Address Labels, which
few, if not any, single-pass disassemblers implement.

With the -l or --address-label option and a supplied prefix, vPICdisasm
will print a label containing the ideally non-numerical supplied prefix
and the address of the disassembled instruction at every instruction. Also,
all relative branch, jump, and call instructions will be formatted to jump to
their designated address label.

This feature enables direct re-assembly of the vPICdisasm's disassembly.
This can be especially useful for quick modification of the PIC program assembly
code without having to manually format the disassembly or adjust the relative
branch, jump, or call distances with every modification to the disassembly.

The -l or --address-label option overrides the default printing of the
addresses alongside disassembly. Destination comments can still be printed.

Example:
$ vpicdisasm -l "A_" sampleprogram.hex
vPICdisasm's disassembly will include address labels that will look like this:
A_0000.

For sample disassembly outputs by vPICdisasm, see the "Sample Disassembly
Outputs" section.

6. Shortcomings
================================================================================
vPICdisasm does not yet support the PIC18 architecture.

vPICdisasm does not disassemble and display alternate versions of the same
encoded instruction. This technically means that some instructions can never be
displayed in the disassembly because another instruction may precede it in
priority.

These features do not affect the accuracy of the disassembler's output, and
may be supported in future versions of vPICdisasm.

7. Source Code
================================================================================
vPICdisasm's source code is heavily commented, because this disassembler was
also a personal learning project of the author.

Operand prefixes (such as "0x" for address operand) can be customized in the
format.h header file.

Field width spacing of the addresses printed alongside disassembly can be
customized in the ui.c source file.

vPICdisasm uses libGIS, a free Atmel Generic, Intel HEX8, and Motorola S-Record
Parser Library to parse formatted files containing PIC program binaries. libGIS
is available for free under both MIT and a Public Domain licenses at:
http://dev.frozeneskimo.com/software_projects/libgis
libGIS is compiled into vPICdisasm--it does not need to be obtained separately.

8. Sample Disassembly Outputs
================================================================================
Here are a few sample disassembly outputs illustrating the various formatting
options and disassembly settings vPICdisasm supports:

$ vpicdisasm sampleprogram.hex
   0:   movlw 0x0
   1:   tris 0x06
   2:   movlw 0xFF
   3:   movwf 0x06
   4:   goto 0x004

$ vpicdisasm --original sampleprogram.hex
   0:	30 00		movlw 0x0
   1:	00 66		tris 0x06
   2:	30 FF		movlw 0xFF
   3:	00 86		movwf 0x06
   4:	28 04		goto 0x004

$ vpicdisasm --no-addresses sampleprogram.hex
movlw 0x0
tris 0x06
movlw 0xFF
movwf 0x06
goto 0x004

$ vpicdisasm --literal-bin sampleprogram.hex
   0:   movlw b'00000000'
   1:   tris 0x06
   2:   movlw b'11111111'
   3:   movwf 0x06
   4:   goto 0x004

$ vpicdisasm -l "A_" sampleprogram.hex

org 0x000
A_000 movlw 0x0
A_001 tris 0x06
A_002 movlw 0xFF
A_003 movwf 0x06
A_004 goto A_004
end

$ vpicdisasm --literal-ascii sampleprogram2.hex
   0:   retlw 0x48      ; 'H'
   1:   retlw 0x45      ; 'E'
   2:   retlw 0x4C      ; 'L'
   3:   retlw 0x4C      ; 'L'
   4:   retlw 0x4F      ; 'O'