From b9558c58d4462903dc53fe8726ac29b52cab85ea Mon Sep 17 00:00:00 2001 From: Andy McFadden Date: Sun, 30 Sep 2018 15:10:08 -0700 Subject: [PATCH] Update READMEs --- README.md | 127 ++++++++++++++++++++--------------- SourceGen/Examples/README.md | 19 +++--- 2 files changed, 84 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index 5f27b05..ef8dc8f 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,13 @@ # 6502bench # +[Features](#key-features) - [Getting Started](#getting-started) - [About the Code](#about-the-code) + 6502bench is a code development "workbench" for 6502, 65C02, and 65802/65816 code. It currently features one tool, the SourceGen disassembler. You can download the source code and build it yourself, or click the -"Releases" tab near the top of the github page for pre-built downloads. +["Releases" tab](https://github.com/fadden/6502bench/releases) for +pre-built downloads. ## SourceGen ## @@ -13,72 +16,88 @@ SourceGen converts machine-language programs to assembly-language source code. It has most of the features you will find in other 6502 disassemblers, as well as many less-common ones. -A demo video is available: https://youtu.be/dalISyBPQq8 +### Key Features ### -#### Features #### +- Fully interactive point-and-click GUI. Define labels, set addresses, + add comments, and see the results immediately. Add multi-line comments + and have them word-wrapped automatically. +- The disassembly engine traces code execution, automatically finding all + instructions reachable from a given starting point. Changes to the + processor status flags are tracked, allowing identification of branches + that are always/never taken, accurate cycle count listings, and correct + analysis of 65816 code with variable-width registers. +- Easy generation of assembly source code in populate formats (currently + cc65 and Merlin 32). Cross-assemblers can be invoked from the GUI to + verify correctness. +- Symbols and constants are provided for ROM and operating system entry + points on several popular systems. -Analysis: -- Support for 6502 (including undocumented opcodes), 65C02, and 65816. -- Code flow analyzer traces execution to find all reachable - instructions. Hinting mechanism allows manual specification of - entry points. -- Processor status flags are tracked, allowing automatic detection - of branch-always and branch-never, as well as register widths on - 16-bit CPUs. The analyzer tracks these across subroutine calls and - branches. Cycle counts factor these in automatically. -- Editable labels are generated for every branch and data target. +A demo video is [available on YouTube](https://youtu.be/dalISyBPQq8). + +#### Additional Features #### + +Analyzer: +- Support for 6502, 65C02, and 65816, including undocumented opcodes. +- Hinting mechanism allows manual identification of code, data, and inline + data. +- Editable labels are generated for every branch destination and data target. - Automatic detection and classification of ASCII strings and runs of identical bytes. -- All target-platform-specific stuff is stored in plain text files - loaded at runtime. This includes symbols for ROM entry points - and standard zero-page locations. Additional symbols and overrides - can be specified at the project level. -- Extension scripts can be used to reformat code and identify inline - data that follows JSR/JSL. Code is compiled at run time and - executes in a sandbox. +- Symbol files for ROM entry points, operating system constants, and other + platform-specific data are stored in plain text files. +- Extension scripts can be defined that automatically reformat code and + identify inline data that follows a JSR/JSL. -UI: -- Fully interactive point-and-click GUI. Add labels and multi-line - comments, change addresses, and see the changes immediately. -- Instruction operand formats (hex, decimal, etc) can be set for - individual lines. Symbols that don't match the operands are automatically - offset, allowing simple expressions like "address - 1". -- Full-line comments are automatically word-wrapped, and can be - "boxed" for an authentic retro feel. -- Data areas can be formatted as bytes, words, addresses, and more. - Several types of strings are recognized (null-terminated, length - prefixed, etc). -- "Infinite" undo/redo of all actions. -- Notes can be added that aren't included in generated output. Very - useful for marking up a work in progress. -- Cross-reference tables are generated for every branch and data - target address, as well as for external platform symbols. -- Instruction summaries, including cpu cycles and flags modified, are - shown along with a description of the opcode function. -- Display is configurable for upper/lower case, choice of pseudo-op - names, expression formats, and more. +User interface: +- "Infinite" undo/redo of all operations. +- Cross-reference tables are generated for every branch and data target + address, as well as for external platform symbols. +- Instruction operand formats (hex, decimal, binary, ASCII, symbol) can be + set for individual instructions. References to nearby symbols are offset, + allowing simple expressions like "addr + 1". +- Data areas can be formatted in various formats, including individual + bytes, 16-bit and 24-bit words, addresses, or strings. +- Multi-line comments can be "boxed" for an authentic retro feel. +- Notes can be added that aren't included in generated output. These also + function as color-coded bookmarks. Very useful for marking up a work in + progress. +- Instruction summaries, including CPU cycles and flags modified, are shown + along with a description of the opcode's function. +- Various aspects of the code display can be reconfigured, including + upper/lower case, pseudo-opcode naming, and expression formats. These + choices are not part of the project definition, so everyone can view a + project according to their own personal preferences. -Output: -- Assembly source can be generated for multiple assemblers (currently - cc65 and Merlin 32). -- Cross-assemblers can be launched directly from the generation GUI to - verify output correctness. -- Optional automatic conversion of labels from global to local. -- Symbols may be exported from one project and imported into another - to facilitate multi-binary disassembly. +Code generation: +- Labels can be coaxed from global to local as allowed by the assembler. +- Symbols may be exported from one project and imported into another to + facilitate multi-binary disassembly. -Misc: -- Preset project attributes (CPU type, platform symbol file sets) are defined - for a variety of platforms. -- Project file is stored in a text format, and only holds metadata. None - of the original file is included, allowing the project file to be shared - without violating copyrights (note: may vary depending on local laws). +Miscellaneous: +- All data files are stored in text formats (primarly JSON). +- The project file includes nothing from the data file but a CRC. This may + allow the project to be shared without violating copyrights (subject to + local laws). There are a couple of significant areas where support is currently lacking: - Poor support for multi-bank 65816 files (IIgs OMF, SNES). - No support for alternate character sets (e.g. PETSCII). +## Getting Started ## + +The best way to get started is by working through the tutorial. Launch +SourceGen, hit F1 to open the user manual in your web browser, then scroll +down near the bottom of the index page. Click on "Tutorials", and follow +the instructions. + +The tutorial is one of several examples included in the SourceGen +distribution. The other directories contain project and data files for +completed disassembly projects alongside the original source code, allowing +a direct comparison between how the code was written and how SourceGen can +display it. + + ## About the Code ## All of the code is written in C# .NET, using the (free to download) Visual diff --git a/SourceGen/Examples/README.md b/SourceGen/Examples/README.md index 2e8664e..9d40e2e 100644 --- a/SourceGen/Examples/README.md +++ b/SourceGen/Examples/README.md @@ -7,22 +7,25 @@ project to the original. * Tutorial: a simple project, intended for use with the tutorial in the manual. * A2-lz4fh: two functions for unpacking a simplified form of LZ4 compression. - One is 6502, the other is 65816. + One is 6502, the other is 65816. This is pretty straightforward. [(Full project)](https://github.com/fadden/fhpack) * A2-Amper-fdraw: 6502 code that provides an Applesoft BASIC interface to a machine-language graphics library. The public interface of the - graphics library is defined in a .sym65 file. + graphics library is defined in a .sym65 file. This example has multiple + entry points in a jump table, and requires a bit more effort. [(Full project)](https://github.com/fadden/fdraw) - * A2-HP-CDA: HardPressed Classic Desk Accessory. This is 65816 code - in OMF loader format, which SourceGen doesn't support, so it's a little - rough. - [(Full project)](https://fadden.com/apple2/hardpressed.html) * A2-Zippy: a program for controlling an Apple IIgs CPU accelerator card. 65816 sources, with a little bit of ProDOS 8 and IIgs toolbox usage. + Demonstrates how extension scripts are used during analysis. [(Full project)](https://fadden.com/apple2/misc.html#zippy) + * A2-HP-CDA: HardPressed Classic Desk Accessory. This is 65816 code + in OMF loader format, which SourceGen doesn't support, so it's a little + rough. (This is chiefly here to answer the question, "what does it look + like when you disassemble OMF binaries?") + [(Full project)](https://fadden.com/apple2/hardpressed.html) (You may be wondering why some of the example files have filenames with things like "#061d60" in them. It's a method of preserving the file type -for Apple II files used by some utilities. The potential advantage here -for SourceGen is that the file type often determines the load address, +for Apple II files used by some utilities. The potential advantage for +disassembly is that the file type often determines the load address, possibly removing some initial guesswork.)