=pod

=head1 NAME

B<dumpmasm> - Dump assembly listing using Pharos partitioner

=head1 SYNOPSIS

dumpmasm [...Pharos options...] EXECUTABLE_FILE

dumpmasm --help

@PHAROS_OPTS_POD@

=head1 DESCRIPTION

The B<dumpmasm> command shows the disassembly and function partitioning
results from the Pharos framework.  Function partitioning is the assignment of
instructions to functions.  The dumpmasm command also reports the control flow
graph recovered by the Pharos framework.

The file format is a comma separated value (CSV) format with three primary
record record types:

"PART", address, "INSN", function_address, hex_bytes, mnemonic, operands

"PART", address, "DATA", function_address, hex_bytes, "db", "???"

"FLOW", from_address, to_address, flow_type

The PART/INSN record type represents a disassembled instruction from the
function partitioner (disassembler).  The mnemonic and operands fields are
intended to communicate which instruction was found, but is not an
authoritative disassembly in a rigorously valid MASM format.

The PART/DATA record type represents data discovered in the program by the
function partitioner.  The trailing "???" field was left for future expansion
to include data type information.  In contrast to INSN records, the DATA
records indicate that Pharos does not believe that the bytes represent
executable code.

The FLOW record type describes control flow discovered by the Pharos
framework.  The flow type field is one of several keywords that are documented
in detail in the PDGEdgeType enumeration in the graph.hpp source file.

=head1 OPTIONS

=head2 B<dumpmasm> OPTIONS

The following options are specific to the B<dumpmasm> program.

=over 4

=item B<--format=STRING>

Write output in specified format. The string "csv" is the only valid option,
and also the default, making this option fairly useless in the most recent
version of this command.

=back

@PHAROS_OPTIONS_POD@

=head1 EXAMPLES

dumpmasm test.exe | grep '^"PART"'

dumpmasm test.exe | grep '^"FLOW"'

=head1 ENVIRONMENT

=over 4

@PHAROS_ENV_POD@

=back

=head1 FILES

=over 4

@PHAROS_FILES_POD@

=back

=head1 NOTES

This program is an internal tool used for debugging the function partitioner,
and hasn't been well maintained.

=head1 AUTHOR

Written by the Software Engineering Institute at Carnegie Mellon
University.  The primary author was Cory Cohen.

=head1 COPYRIGHT

Copyright 2018 Carnegie Mellon University.  All rights reserved.  This
software is licensed under a "BSD" license.  Please see I<LICENSE.txt>
for details.

=for comment
head1 SEE ALSO

=cut

Local Variables:
mode:text
indent-tabs-mode:nil
End:
