vPICdisasm - Microchip PIC Disassembler
Note: This project will soon be replaced by ucdisasm.
git clone git://github.com/vsergeev/vPICdisasm.git
Latest source: vpicdisasm-master zip
Arch Linux AUR Package: http://aur.archlinux.org/packages.php?ID=46700
Please feel free to report any issues at github or by email at vsergeev at gmail.
- Release 1.3 - 04/03/2011
- CRITICAL FIX: Fixed S-Record reading bug that was ignoring valid data records.
- Added output file support by
- Added standard input support with the “-“ file argument, meaning the disassembler now supports piped input.
- Improved Intel HEX8 / Motorola S-Record auto-detection by first character rather than file extension.
- Thanks to Thomas for all four of the above fixes and suggestions!
- Added printing of original opcode data alongside disassembly with
- Release 1.2 - 07/28/2010
- Added support for Baseline and Mid-Range Enhanced PIC cores.
- Updated destination register operand formatting to print W/F instead of 0/1.
- Renamed source files to make more sense and for better organization of code.
- Release 1.1 - 07/20/2009
- Fixed handling of newlines (sometimes found at the end of program files) so an “invalid record” error doesn’t appear when a newline is encountered.
- CRITICAL FIX: Fixed reading and disassembly of odd byte length records in Intel HEX8 and Motorola S-Record files. Special thanks to Ahmed for discovery and patch!
- Fixed a few small bugs/typos for cleaner compilation.
- Release 1.0 - 01/06/2007
- Initial release.
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.
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.
Simply by running,
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”.
For most purposes:
$ vpicdisasm <PIC program file>
$ vpicdisasm sampleprogram.hex
- for standard input.
vPICdisasm will assume the Mid-Range PIC architecture by default. You can specifiy an alternate architecture with the
$ vpicdisasm -a enhanced sampleprogram.hex
vPICdisasm will auto-recognize Intel HEX8, and Motorola S-Record files by their first character. However, the
--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.
--out-file «output file»
Specify an output file for writing instead of the standard output. The output file
- is also synonymous for standard output.
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
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).
vPICdisasm can represent literal operands in either hexadecimal, decimal, or binary bases. The base can be specified with the
Display the ASCII value of a literal operand in an assembly comment.
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-destination-comments options, respectively.
See the Ghetto Address Labels section.
--help option will print a brief usage summary, including supported program options and file types. The
--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.
Additional Usage Information
Additional usage information from the program’s help is provided below.
Usage: vpicdisasm <option(s)> <file> Disassembles PIC program file <file>. Use - for standard input. Written by Vanya A. Sergeev - <email@example.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
Ghetto Address Labels
vPICdisasm supports a unique formatting feature: Ghetto Address Labels, which few, if not any, single-pass disassemblers implement.
--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.
--address-label option overrides the default printing of the addresses alongside disassembly. Destination comments option can still be used.
$ 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.
- 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.
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 here. libGIS is compiled into vPICdisasm—it does not need to be obtained separately.
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'