mirror of
https://github.com/fadden/6502bench.git
synced 2024-11-30 01:50:10 +00:00
cd937709fa
Altered the address region edit UI a little to improve clarity. Also, close the hex dump viewer window when Escape is hit. (The tool windows don't have "cancel" buttons, so the key has to be handled explicitly.)
687 lines
33 KiB
HTML
687 lines
33 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<meta charset="utf-8"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
|
|
<link rel="stylesheet" href="main.css"/>
|
|
<title>Using SourceGen - 6502bench SourceGen</title>
|
|
</head>
|
|
|
|
<body>
|
|
<div id="content">
|
|
<h1>SourceGen: Using SourceGen</h1>
|
|
<p><a href="index.html">Back to index</a></p>
|
|
|
|
<h2 id="starting-new">Starting a New Project</h2>
|
|
|
|
<p>Select <samp>File > New</samp>, or if no project is open, you
|
|
can click the <samp>Start new project</samp> button.
|
|
This opens the <samp>Create New Project</samp> window.</p>
|
|
<p>Start by selecting your target system from the tree on the left.
|
|
The panel on the right will show the CPU that will be selected, as well
|
|
as the symbol files and extension scripts that will be loaded by default.
|
|
All of these may be overridden later from the project properties.
|
|
(If the description in the panel on the right says
|
|
"<samp>[placeholder]</samp>", it means that the system doesn't yet have
|
|
a set of symbols defined for it.)</p>
|
|
|
|
<p>Next, click the <samp>Select File...</samp> button. Pick the file you
|
|
wish to disassemble. The dialog will update with the pathname and some notes
|
|
about the file's size. Click <samp>OK</samp> if all looks good to create the
|
|
project.</p>
|
|
<p><strong>NOTE:</strong> Support for very large 65816 programs is
|
|
incomplete. The maximum size for a data file is limited to 1 MiB.</p>
|
|
|
|
<p>The first time you save the project (with <samp>File > Save</samp>),
|
|
you will be prompted for the project name. It's best to use the
|
|
data file's name with "<samp>.dis65</samp>" added, so this will be set as
|
|
the default. The data file's name is not stored in the project file,
|
|
so if you pick a different name, or save the project in a different
|
|
directory, you will have to select the data file manually whenever you
|
|
open the project.</p>
|
|
|
|
|
|
<h2 id="opening">Opening an Existing Project</h2>
|
|
|
|
<p>Select <samp>File > Open</samp>, or if no project is open, you
|
|
can click the <samp>Open existing project</samp> button.
|
|
Select the .dis65 project file from the standard file dialog.</p>
|
|
<p>SourceGen will try to open a data file with the project's name,
|
|
minus the ".dis65". If it can't find a file with that name, or if there's
|
|
something wrong with it (e.g. the CRC doesn't match), you will be given
|
|
the opportunity to specify the location of the data file to use.</p>
|
|
|
|
<p>If non-fatal problems with the file are detected, a warning will be
|
|
shown. If it's something simple, like a missing .sym65 or extension
|
|
script file, you'll be notified. If it's something more complicated,
|
|
e.g. the project has a comment on an offset that doesn't exist, you
|
|
will be warned that the problematic data has been deleted, and will be
|
|
lost if the project is saved. By default, such a project will be opened
|
|
in read-only mode, though you can override this in the dialog. You will
|
|
also be given the opportunity to simply cancel loading the project.</p>
|
|
|
|
<p>The locations of the last few projects you've worked with are saved
|
|
in the application settings. You can access them from
|
|
<samp>File > Recent Projects</samp>. If no project is open, buttons
|
|
that open the two most-recently-opened projects will be available.</p>
|
|
|
|
|
|
<h2 id="working">Working With a Project</h2>
|
|
|
|
<p>The main project window is divided into five areas:</p>
|
|
<ol>
|
|
<li>Center: the code list. If no project is open, this will instead
|
|
have buttons to open a new or existing project.</li>
|
|
<li>Top left: cross-reference list.</li>
|
|
<li>Bottom left: notes list.</li>
|
|
<li>Top right: symbols list.</li>
|
|
<li>Bottom right: info on selected line.</li>
|
|
</ol>
|
|
|
|
<p>Most actions are performed in the center code list. All of the
|
|
sub-windows can be resized. The window sizes and column widths are
|
|
saved in the application settings file.</p>
|
|
|
|
<p>A toolbar near the top of the screen has some shortcut buttons.
|
|
If you hover your mouse over them, a tooltip with an explanation will
|
|
appear.</p>
|
|
|
|
<p>A status bar at the bottom displays a summary of the amount of
|
|
code, data, and uninitialized data (variable storage or junk) found
|
|
in the program. These values are updated as you work.</p>
|
|
|
|
|
|
<h3 id="code-list">Code List</h3>
|
|
|
|
<p>The code list provides a view of the code being disassembled. Each
|
|
line may be an instruction, data item, long comment, note, or
|
|
assembler directive.</p>
|
|
<p>The list is divided into columns:</p>
|
|
<ul>
|
|
<li><b>Offset</b>. The offset within the file where the instruction
|
|
or data item starts. Throughout the UI, file offsets are shown as
|
|
six-digit hex values with a leading '+'.</li>
|
|
<li><b>Address</b>. The address where the assembled code will execute.
|
|
For 8-bit CPUs this is shown as a 4-digit hex number, for 16-bit
|
|
CPUs the bank is shown as well. Double-click on this field to open the
|
|
<a href="editors.html#address">Edit Address</a> dialog.</li>
|
|
<li><b>Bytes</b>. Shows up to four bytes from the data file that
|
|
correspond to the instruction or data. To see the full dump of
|
|
a longer item, such as an ASCII string, double-click on the field
|
|
to open the
|
|
<a href="tools.html#hexdump">Hex Dump Viewer</a>. This is
|
|
a floating window, so you can keep it open while you work.
|
|
Double-clicking in the bytes column while the window is open will
|
|
update the viewer's position and selection.</li>
|
|
<li><b>Flags</b>. This shows the state of the status flags as they
|
|
are before the instruction is executed. Double-click on this
|
|
field to open the
|
|
<a href="editors.html#flags">Edit Status Flag Override</a> dialog.</li>
|
|
<li><b>Attributes</b>. Some instructions and data items have
|
|
interesting attributes.
|
|
'@' indicates an entry point,
|
|
'T' means one or more bytes has an analyzer tag (code start/stop/skip),
|
|
'#' means execution will not continue to the following instruction,
|
|
'>' is shown for branch targets, and
|
|
'!' appears when a conditional branch is never taken.
|
|
(This column is rarely useful and can be hidden.)</li>
|
|
<li><b>Label</b>. If a label has been defined for this offset, by
|
|
the user or generated automatically, it will appear here. Also,
|
|
full-line items like long comments and notes will start in this
|
|
field. Double-click on this field to open the
|
|
<a href="editors.html#label">Edit Label</a> dialog.</li>
|
|
<li><b>Opcode</b>. The instruction or pseudo-opcode mnemonic.
|
|
If an instruction is embedded inside this one, a ▼ symbol
|
|
will appear.
|
|
If you double-click this field for an instruction or data item
|
|
whose operand refers to an address in the file, the selection will
|
|
jump to that location. If the operand is a local variable, the
|
|
selection will jump to the point where the variable was defined.</li>
|
|
<li><b>Operand</b>. The instruction or data operand. Data operands
|
|
may span a large number of bytes. Double-click on this field to
|
|
open the
|
|
<a href="editors.html#instruction-operand">Edit Instruction Operand</a>
|
|
or <a href="editors.html#data-operand">Edit Data Operand</a> dialog, as
|
|
appropriate. (Note you can shift-double-click on data items to
|
|
edit multiple lines.)</li>
|
|
<li><b>Comment</b>. End-of-line comment, generally shown with a ';'
|
|
prefix. If enabled, cycle counts will appear here. Double-click
|
|
on this field to open the
|
|
<a href="editors.html#comment">Edit Comment</a> dialog.</li>
|
|
</ul>
|
|
|
|
<p>Double-clicking anywhere on a line with a note or long comment will
|
|
open the
|
|
<a href="editors.html#note">Edit Note</a> or
|
|
<a href="editors.html#long-comment">Edit Long Comment</a> dialog,
|
|
respectively.</p>
|
|
|
|
<p>The code list is a standard Windows list view. You can left-click
|
|
to select an item, ctrl-left-click to toggle individual items on and
|
|
off, and shift-left-click to select a range. You can select all lines
|
|
with <samp>Edit > Select All</samp>. Resize columns by
|
|
left-clicking on the divider in the header and dragging it.</p>
|
|
<p>Selecting any part of a multi-line item, such as a long comment
|
|
or character string, effectively selects the entire item.</p>
|
|
|
|
<p>Right-clicking opens a menu. The contents are the same as those in
|
|
the <samp>Actions</samp> menu item in the menu bar. The set of options
|
|
that are enabled will depend on what you have selected in the main window.</p>
|
|
<ul>
|
|
<li><a href="editors.html#instruction-operand">Edit Operand</a>. Opens the
|
|
Edit Instruction Operand or Edit Data Operand window, depending on
|
|
what's selected.
|
|
Enabled when a single instruction line is selected, or when one
|
|
or more data lines are selected.</li>
|
|
<li><a href="editors.html#label">Edit Label</a>. Sets the label
|
|
at that offset. Enabled when a single instruction or data line is
|
|
selected.</li>
|
|
<li><a href="editors.html#comment">Edit Comment</a>. Sets the
|
|
comment at that offset. Enabled when a single instruction or data
|
|
line is selected.</li>
|
|
<li><a href="editors.html#long-comment">Edit Long Comment</a>. Sets
|
|
the long comment at that offset. Enabled when a single instruction
|
|
or data line, or an existing long comment, is selected.</li>
|
|
<li><a href="editors.html#note">Edit Note</a>. Sets the note at
|
|
that offset. Enabled when a single instruction or data line, or
|
|
an existing note, is selected.</li>
|
|
<li><a href="editors.html#address">Create/Edit Address Region</a>.
|
|
Sets the assembly address at the selected offset. Can be used
|
|
to set a start point with a floating end, or specify a region
|
|
with a fixed end point (useful for code that get relocated).
|
|
Enabled when the first line selected is code, data, or an address
|
|
start directive.</li>
|
|
<li><a href="editors.html#flags">Override Status Flags</a>. Changes
|
|
the status flags at that offset. Enabled when a single instruction
|
|
line is selected.</li>
|
|
<li><a href="editors.html#project-symbol">Edit Project Symbol</a>.
|
|
Sets the name, value, and comment of the project symbol. Enabled
|
|
when a single equate directive, generated from a project symbol, is
|
|
selected.</li>
|
|
<li><a href="editors.html#lvtable">Create Local Variable Table</a>.
|
|
Create a new local variable table.</li>
|
|
<li><a href="editors.html#lvtable">Edit Prior Local Variable Table</a>.
|
|
Modify or delete entries in the most recently defined local
|
|
variable table.</li>
|
|
<li><a href="visualization.html#vis-and-sets">Create/Edit Visualization Set</a>.
|
|
Create a new visualization set or edit an existing set.</li>
|
|
</ul>
|
|
<ul>
|
|
<li><a href="#atags">Analyzer Tags</a> (Tag Address As Code Start Point,
|
|
Tag Address As Code Stop Point, Tag Bytes As Inline Data,
|
|
Remove Analyzer Tags).
|
|
Enabled when one or more code and data lines are selected. Remove
|
|
Analyzer Tags is only enabled when at least one line has tags. The
|
|
keyboard shortcuts are two-key combinations.</li>
|
|
</ul>
|
|
<ul>
|
|
<li><a href="#address-table">Format Address Table</a>. Formats
|
|
a series of bytes as parts of a table of addresses.</li>
|
|
<li><a href="#toggle-single">Toggle Single-Byte Format</a>. Toggles
|
|
a range of lines between default format and single-byte format. Enabled
|
|
when one or more data lines are selected.</li>
|
|
<li><a href="#format-as-word">Format As Word</a>. Formats two bytes as
|
|
a 16-bit little-endian word.</li>
|
|
<li><a href="#remove-formatting">Remove Formatting</a>. Reverts
|
|
instruction and data operand formats to the default. Clears
|
|
embedded labels.</li>
|
|
<li>Delete Note / Long Comment. Deletes the selected note or long
|
|
comment. Enabled when a single note or long comment is selected.</li>
|
|
<li><a href="tools.html#hexdump">Show Hex Dump</a>. Opens the hex dump
|
|
viewer, with the current selection highlighted. Always enabled. If
|
|
nothing is selected, the viewer will open at the top of the file.</li>
|
|
</ul>
|
|
|
|
|
|
<h3 id="undo">Undo & Redo</h3>
|
|
|
|
<p>You can undo a change with <samp>Edit > Undo</samp>, or
|
|
<kbd class="key">Ctrl+Z</kbd>. You can redo a
|
|
change with <samp>Edit > Redo</samp>, <kbd class="key">Ctrl+Y</kbd>,
|
|
or <kbd class="key">Ctrl+Shift+Z</kbd>.</p>
|
|
<p>All changes to the project, including changes to the project properties,
|
|
are added to the undo/redo buffer. This has no fixed size limit, so no
|
|
matter how much you change, you can always undo back to the point where
|
|
the project was opened.</p>
|
|
<p>The undo history is not saved as part of the project. Closing a project
|
|
clears it.</p>
|
|
|
|
|
|
<h3 id="references">References Window</h3>
|
|
|
|
<p>When a single instruction or data line is selected in the main window,
|
|
all references to that offset will be shown in the References window.
|
|
For each reference, the file offset, address, and some details about the
|
|
type of reference will be shown.</p>
|
|
|
|
<p>The reference type indicates whether the origin is an instruction or
|
|
data operand, and provides an indication of the nature of the reference:</p>
|
|
<ul>
|
|
<li>call - subroutine call
|
|
(e.g. <code>JSR addr</code>, <code>JSL addr</code>)</li>
|
|
<li>branch - conditional or unconditional branch
|
|
(e.g. <code>JMP addr</code>, <code>BCC addr</code>)</li>
|
|
<li>read - read from memory
|
|
(e.g. <code>LDA addr</code>, <code>BIT addr</code>)</li>
|
|
<li>write - write to memory
|
|
(e.g. <code>STA addr</code>)</li>
|
|
<li>rmw - read-modify-write
|
|
(e.g. <code>LSR addr</code>, <code>TSB addr</code>)</li>
|
|
<li>ref - reference to address by instruction
|
|
(e.g. <code>LDA #<addr</code>, <code>PEA addr</code>)</li>
|
|
<li>data - reference to address by data
|
|
(e.g. <code>.DD2 addr</code>)</li>
|
|
</ul>
|
|
<p>References from instructions that use indexed addressing
|
|
(e.g. <code>LDA addr,Y</code>) will also show "idx" to indicate that
|
|
the instruction is using the location as a base address.</p>
|
|
<p>References from instructions that treat the address as a pointer
|
|
(e.g. <code>LDA (dp),Y</code>) will show "ptr". This makes it easy
|
|
to identify the locations that are reading or writing through the
|
|
pointer from those that are reading or writing the pointer itself.</p>
|
|
<p>This will be prefixed with "<samp>Sym</samp>" or "<samp>Oth</samp>"
|
|
to indicate whether or not the reference used the label at the current
|
|
address. To understand this, consider that addresses can be referenced
|
|
in different ways. For example:</p>
|
|
<pre>
|
|
LDA DATA0
|
|
LDX DATA0+1
|
|
RTS
|
|
DATA0 .DD1 $80
|
|
DATA1 .DD2 $90
|
|
</pre>
|
|
<p>Both <code>DATA0</code> and <code>DATA1</code> are accessed, but
|
|
both operands used <code>DATA0</code>. When the <code>DATA0</code> line
|
|
is selected in the code list, the references window will show the
|
|
<code>LDA</code> and <code>LDX</code> instructions, because both
|
|
instructions referenced it. When <code>DATA1</code> is selected, the
|
|
references window will show the <code>LDX</code>, because that
|
|
instruction accessed <code>DATA1</code>'s location even though it didn't
|
|
use the symbol. To make the difference clear, the lines in the references
|
|
window will either show "<samp>Sym</samp>" (to indicate that the symbol
|
|
at the selected line was referenced) or "<samp>Oth</samp>" (to indicate
|
|
that some other symbol, or no symbol, was used).</p>
|
|
|
|
<p>When an equate directive (generated for platform and project
|
|
symbols) or local variable assignment is selected, the References
|
|
window will show all references to that symbol. Unlike in-file
|
|
references, only the uses of that symbol are shown. So if you have
|
|
both a project symbol and a local variable for address $30, they
|
|
will show disjoint sets of references. Furthermore, if you explicitly
|
|
format an instruction operand as hex, e.g. <code>LDA $30</code>, it will
|
|
not appear in either set because it's not a symbolic reference.</p>
|
|
<p>The cross-reference data is used to generate the set of equate
|
|
directives at the top of the listing. If nothing references a platform
|
|
or project symbol, an equate directive will not be generated for it.</p>
|
|
|
|
<p>Double-clicking on a reference moves the code list selection to that
|
|
reference, and adds the previous selection to the navigation stack.</p>
|
|
|
|
|
|
<h3 id="notes">Notes Window</h3>
|
|
|
|
<p>When you add a note, it will also be added to this window.
|
|
Double-clicking on a note will jump directly to it, and add the previous
|
|
selection to the navigation stack. This makes notes useful as bookmarks.</p>
|
|
|
|
|
|
<h3 id="symbols">Symbols Window</h3>
|
|
|
|
<p>All known <a href="intro-details.html#about-symbols">symbols</a> are shown
|
|
here. The filter buttons allow you to screen out symbols you're not
|
|
interested in, such as platform symbols or constants. The filters are:</p>
|
|
<ul>
|
|
<li><samp>User</samp> - include "user labels", i.e. labels that
|
|
were entered by the user.</li>
|
|
<li><samp>NonU</samp> - include non-unique (local) labels.</li>
|
|
<li><samp>Proj</samp> - include project symbols.</li>
|
|
<li><samp>Plat</samp> - include platform symbols.</li>
|
|
<li><samp>PreL</samp> - include address region pre-labels.</li>
|
|
<li><samp>Auto</samp> - include auto-generated labels.</li>
|
|
<li><samp>Addr</samp> - include symbols for addresses. This
|
|
includes all labels, as well as addresses defined in project
|
|
and platform symbol tables.</li>
|
|
<li><samp>Cnst</samp> - include constants, defined in project
|
|
and platform symbol tables.</li>
|
|
</ul>
|
|
|
|
<p>Clicking on one of the column headers will sort the list on that
|
|
field. Click a second time to reverse the sort direction.</p>
|
|
|
|
<p>Double-clicking on an auto or user label will jump to that label, and
|
|
add the previous selection to the navigation stack. This can be a handy
|
|
way to move around the file, jumping from label to label.</p>
|
|
|
|
<p>The "type" column uses a two-letter code to identify the symbol's
|
|
type and scope. The first letter is one of A (auto), U (user),
|
|
P (platform), J (project), R (pre-label), or V (variable).
|
|
The second letter is one of N (non-unique local), L (local), G (global),
|
|
X (exported), E (external), or C (constant).</p>
|
|
|
|
|
|
<h3 id="info">Info Window</h3>
|
|
|
|
<p>Some additional information about the currently-selected line is
|
|
shown, such as the formatting applied to the operand. If the operand
|
|
has a default format, any automatically-generated format will be noted.
|
|
For an instruction,
|
|
a summary is shown that includes the cycle count, flags affected, and a
|
|
brief description of what the instruction does. The latter can be
|
|
especially handy for undocumented instructions.</p>
|
|
<p>If multiple lines are selected, the number of selected lines and the
|
|
number of bytes spanned by the selection will be shown.</p>
|
|
|
|
|
|
<h3 id="messages">Messages Window</h3>
|
|
|
|
<p>Sometimes a change will invalidate an earlier change. For example,
|
|
suppose you add a code stop point, and format the data that follows
|
|
as a string. Later on you change it to a code start point. You now have
|
|
a block of executable code with a string format record sitting in the
|
|
middle of it. SourceGen tries very hard not to throw away anything
|
|
you've done, but it will ignore anything invalid.</p>
|
|
<p>If a problem like this is encountered, an entry is added to a list
|
|
of messages displayed at the bottom of the main window. Each entry identifies
|
|
the nature of the problem, the severity of the problem, the offset where
|
|
it occurred, and what was done to resolve it. The problem categories
|
|
include:</p>
|
|
<ul>
|
|
<li>Hidden label: a label placed on code or data is now stuck in the
|
|
middle of a multi-byte instruction or data item.</li>
|
|
<li>Hidden local variable table: a local variable table has been
|
|
placed in the middle of a multi-byte item.</li>
|
|
<li>Hidden visualization: a visualization set has been
|
|
placed in the middle of a multi-byte item.</li>
|
|
<li>Unresolved weak ref: a reference to a non-existent symbol was found.</li>
|
|
<li>Non-addressable label reference: a code or data operand has a
|
|
reference to a label defined in a non-addressable section of the
|
|
file. (The generated code will likely fail to assemble.)</li>
|
|
<li>Invalid offset or length: the offset or length in a format object
|
|
had an invalid value.</li>
|
|
<li>Invalid descriptor: the format descriptor is inappropriate,
|
|
e.g. formatting an instruction as a string.</li>
|
|
<li>Bank overrun: the generated code would run past address $ffff.
|
|
The handling of this in generated code is assembler-dependent.</li>
|
|
</ul>
|
|
<p>The "context" column will provide additional detail about the problem,
|
|
and the "resolution" column will indicate how it's being handled. In most
|
|
cases, the offending item will be ignored.</p>
|
|
<p>Double-clicking on an entry will jump to that offset.</p>
|
|
<p>The message list will not appear if there are no messages. You can
|
|
hide the list by clicking on the <samp>Hide</samp> button to the left of
|
|
the messages. Un-hide the list by clicking on the <samp>N messages</samp>
|
|
button at the bottom-right corner of the application window.</p>
|
|
|
|
|
|
<h3 id="navigation">Navigation</h3>
|
|
|
|
<p>The simplest way to move through the code list is with the scroll wheel
|
|
on your mouse, or by left-clicking and dragging the scroll bar. You
|
|
can also use <kbd class="key">PgUp</kbd>/<kbd class="key">PgDn</kbd>
|
|
and the arrow keys.</p>
|
|
|
|
<p>Use <samp>Navigate > Find</samp> to search for text. This performs
|
|
a case-insensitive text search on the label, opcode, operand, and comment
|
|
fields.
|
|
Use <samp>Navigate > Find Next</samp> to find the next match, and
|
|
<samp>Navigate > Find Previous</samp> to find the previous match.
|
|
Note "next" is always downward, and "previous" is always upward,
|
|
regardless of the direction of the initial search chosen in the
|
|
Find dialog.</p>
|
|
|
|
<p>Use <samp>Navigate > Go To</samp> to jump to an offset, address,
|
|
or label. Remember that offsets and addresses are always hexadecimal,
|
|
and offsets start with a '+'. If you have a label that is also a
|
|
valid hexadecimal address, like "FEED", the label takes precedence. To
|
|
jump to the address write "$FEED" instead. If you enter a non-unique label,
|
|
the selection will jump to the nearest instance.</p>
|
|
|
|
<p>If an instruction or data line has an operand that references an address
|
|
in the file, you can navigate to the operand's location with
|
|
<samp>Navigate > Jump to Operand</samp>. You can also do this by
|
|
double-clicking in the opcode column.</p>
|
|
|
|
<p>When you edit something, lines throughout the listing can change. This
|
|
is different from a source code editor, where editing a line just changes
|
|
that line. To allow you to watch the effects changes have, the undo/redo
|
|
commands try to keep the listing in the same position.
|
|
If you want to go to the place where the last change (i.e. the change
|
|
that will be undone by the next Undo operation) was made,
|
|
<samp>Navigate > Go to Last Change</samp> will jump to the first offset
|
|
associated with the most recent change.
|
|
If the last change was to the project properties, it will jump to the
|
|
first offset in the file.</p>
|
|
|
|
<p>When you jump around, e.g. by double-clicking on an opcode or an entry
|
|
in one of the side windows, the previously-selected line is added to
|
|
a navigation stack. You can use <samp>Navigate > Nav Forward</samp> and
|
|
<samp>Navigate > Nav Backward</samp> to move forward and backward
|
|
through the stack. (The curly arrows on the left side of the toolbar may
|
|
be more convenient. You can use
|
|
<kbd class="key">Alt+LeftArrow</kbd> / <kbd class="key">Alt+RightArrow</kbd>,
|
|
or <kbd class="key">Ctrl+-</kbd> / <kbd class="key">Ctrl+Shift+-</kbd>,
|
|
as keyboard shortcuts.)</p>
|
|
|
|
|
|
<h3 id="atags">Adding and Removing Analyzer Tags</h3>
|
|
|
|
<p><i>(Note: These were referred to as code/data "hints" in older
|
|
versions of SourceGen.)</i></p>
|
|
|
|
<p>To set code start or stop points, select the desired offsets and
|
|
use <samp>Actions > Tag Address As Code Start Point</samp>
|
|
(or <samp>Stop Point</samp>). Because these indicate a transition
|
|
between code and data regions, there is rarely any need to tag
|
|
multiple consecutive bytes. For this reason, only the first byte on
|
|
each selected line will be tagged.</p>
|
|
|
|
<p>For inline data that follows a
|
|
<code>JSR</code>/<code>JSL</code>/<code>BRK</code>,
|
|
you need to cover the entire range, so every byte
|
|
in every selected line is tagged when you select
|
|
<samp>Tag Bytes As Inline Data</samp>. Similarly, the
|
|
<samp>Remove Analyzer Tags</samp> menu item will remove tags from
|
|
every byte.</p>
|
|
|
|
<p>Tip: while code start points and inline data tagging are both very
|
|
important, code <i>stop</i> points are rarely useful. The code
|
|
analyzer is pretty good at separating code from data. If you find
|
|
yourself using stop points frequently, you're probably Doing It Wrong.</p>
|
|
|
|
<p>If you're having a hard time selecting just the right bytes because
|
|
the instructions are caught up in a multi-byte data item, such as an
|
|
auto-detected character string, you can disable uncategorized data analysis
|
|
(the thing that creates the <code>.STR</code> and <code>.FILL</code>
|
|
ops for you). You can do this from the
|
|
<a href="settings.html#project-properties">project properties</a> editor,
|
|
or simply by hitting <kbd class="key">Ctrl+D</kbd>. Hit that, tag the
|
|
byte or bytes, then hit it again to re-enable the
|
|
string & fill analyzer.</p>
|
|
<p>Another approach is to use the <samp>Toggle Single-Byte Format</samp>
|
|
menu item to "flatten" the item, explicitly formatting everything as
|
|
individual hex bytes.</p>
|
|
|
|
|
|
<h3 id="address-table">Format Address Table</h3>
|
|
|
|
<p>Tables of addresses are fairly common. Sometimes you'll find them as a
|
|
series of 16-bit words, like this:</p>
|
|
<pre>
|
|
jmptab .dd2 func1
|
|
.dd2 func2
|
|
.dd2 func3
|
|
</pre>
|
|
|
|
<p>While that's fairly common in 16-bit software, 8-bit software often splits
|
|
the high and low bytes into separate arrays, like this:</p>
|
|
<pre>
|
|
jmptabl .dd1 <func1
|
|
.dd1 <func2
|
|
.dd1 <func3
|
|
jmptabh .dd1 >func1
|
|
.dd1 >func2
|
|
.dd1 >func3
|
|
</pre>
|
|
|
|
<p>Sometimes the tables contain <code>address - 1</code>, because the
|
|
values are to be pushed onto the stack for an <code>RTS</code> call.</p>
|
|
|
|
<p>While the <code>.dd2</code> case is easy to format with the data
|
|
operand editor, formatting addresses whose components are split into
|
|
multiple tables can be tedious. Even in the easy case, you may want
|
|
to create labels and set code start points for each item.</p>
|
|
|
|
<p>The Address Table Formatter helps you associate symbols with the
|
|
addresses in the table. It works for simple and "split" tables.</p>
|
|
<p>To use it, start by selecting the entire table. In the examples above,
|
|
you would select all 6 bytes. The number of bytes in each part of a
|
|
split table must be equal: here, it's 3 low bytes, followed by 3 high
|
|
bytes. If the number of bytes selected can't be evenly divided by the
|
|
number of parts -- two parts for 16-bit data, three parts for 24-bit data --
|
|
the formatter will report an error.</p>
|
|
<p>With the data selected, open the format dialog with
|
|
<samp>Actions > Format Split-Address Table</samp>. The rather
|
|
complicated dialog is split into sections.</p>
|
|
<ul>
|
|
<li>Address Characteristics: select whether the table has 16-bit
|
|
addresses or 24-bit addresses. (24-bit addresses are disabled if you
|
|
don't have the CPU set to 65816.) If the table is split into individual
|
|
sub-tables for low bytes and high bytes, check the <samp>Parts are split
|
|
across sub-tables</samp> box. If the address parts are being pushed
|
|
on the stack for an <code>RTS</code>/<code>RTL</code>,
|
|
check the <samp>Adjusted for RTS/RTL</samp> box to adjust them by 1.</li>
|
|
<li>Low Byte Source: indicate which part of the table or word holds the
|
|
low bytes. For common little-endian words, the low bytes come first. In
|
|
the split-table example above, the low bytes came first, followed by the
|
|
high bytes, so you would select <samp>first part of selection</samp>.
|
|
If they were stored the other way around, you would click
|
|
<samp>second part</samp> instead.</li>
|
|
<li>High Byte Source: indicate which part of the table or word holds
|
|
the high bytes. For a 16-bit address this will be the part you didn't
|
|
pick for the low bytes.
|
|
Sometimes, if all addresses land on the same 256-byte page, the high byte
|
|
will be a constant in the code, and only the low bytes will be stored in
|
|
a table. If that's the case, select <samp>Constant</samp>, and enter
|
|
the high byte in the text box.
|
|
(Decimal, hex, and binary are accepted.)</li>
|
|
<li>Bank Byte Source: for 24-bit addresses, you can select <samp>Nth part of
|
|
selection</samp>, which will just use whichever part you didn't specify for
|
|
the low and high bytes. If the table holds 16-bit addresses, you can
|
|
use the <samp>Constant</samp> field to specify the data bank.</li>
|
|
<li>Options: if the table holds the addresses of executable code, check
|
|
the <samp>Tag targets as code start points</samp> box. If the target
|
|
address hasn't been identified by the code analyzer through some
|
|
other execution path, it will be tagged as a code start point.</li>
|
|
<li>Generated Addresses: this shows the full list of addresses that are
|
|
generated with the current set of parameters. Each address is shown with
|
|
a file offset and a symbol. If the address can't be mapped within the
|
|
file, the offset is shown as dashes instead. If the address can be
|
|
mapped, and it already has a user-specified label, the label will be
|
|
shown. If no label was found, the table will show "<code>(+)</code>",
|
|
indicating that a permanent label will be added at the target offset. If
|
|
everything is set up correctly, and the addresses fall entirely within
|
|
the program, you shouldn't see any unknown entries here.</li>
|
|
</ul>
|
|
|
|
<p>For a 16-bit address, you have three choices: low byte first, high byte
|
|
first, or low byte only with a constant high byte. For a 24-bit address
|
|
the set of possibilities expands, but is essentially the same: pick the
|
|
order in which things appear, using fixed constants if desired.</p>
|
|
|
|
<p>A message at the top of the screen shows how many bytes are selected.
|
|
It also tells you how many groups there are, but unlike the data operand
|
|
formatter, the split-address table formatter doesn't care about group
|
|
boundaries. For this reason, tables do not have to be contiguous in
|
|
memory. The low bytes and high bytes could be on separate 256-byte
|
|
pages. You just need to have all of the data selected.</p>
|
|
|
|
<p>It should be mentioned that SourceGen does not record the fact that the
|
|
data in question is part of a table. The formatting, labels, and code
|
|
start point tags are applied as if you entered them all individually by
|
|
hand. The formatter is just significantly more convenient. It also
|
|
does everything as a single undoable action, so if it comes out looking
|
|
wrong, just hit "undo" and try something else.</p>
|
|
|
|
|
|
<h3 id="toggle-single">Toggle Single-Byte Format</h3>
|
|
|
|
<p>The <samp>Toggle Single-Byte Format</samp> feature provides a quick
|
|
way to change a range of bytes to single bytes
|
|
or back to their default format. It's equivalent to opening the Edit
|
|
Data Operand dialog and selecting <samp>Single bytes</samp> displayed
|
|
as hex, or selecting <samp>Default</samp>.</p>
|
|
<p>This can be handy if the default format for a range of bytes is a
|
|
string, but you want to see it as bytes or set a label in the middle.</p>
|
|
|
|
|
|
<h3 id="format-as-word">Format As Word</h3>
|
|
|
|
<p>This is a quick way to format pairs of bytes as 16-bit words. It's
|
|
equivalent to opening the Edit Data Operand dialog and selecting
|
|
"16-bit words, little-endian", displayed as hex.</p>
|
|
|
|
<p>To avoid some confusing situations, it only works on sets of
|
|
single-byte values. This means, for example, that you can't select a
|
|
10-byte string and have it turn into five 16-bit words. You can select as
|
|
many bytes as you want, but they must come in pairs. (Remember that you
|
|
can turn off auto-generation of strings and <code>.FILL</code>s with
|
|
<a href="#toggle-data">Toggle Data Scan</a>.)</p>
|
|
<p>As a special case, if you select a single byte, the following byte will
|
|
also be selected. This won't work if the following byte is part of a
|
|
multi-byte data item, is the start of a new region (see
|
|
<a href="editors.html#data-operand">Edit Data Operand</a> for a definition of
|
|
what splits a region), or is the last byte in the file.</p>
|
|
|
|
|
|
<h3 id="remove-formatting">Remove Formatting</h3>
|
|
|
|
<p>Removes instruction and data operand formatting from the selected lines.
|
|
This removes the visible formatting as well as any formatting instructions
|
|
that got embedded inside multi-byte data items. (You will be notified of
|
|
such things in the <a href="#messages">message list</a>.)</p>
|
|
|
|
<p>This will also remove any labels that are embedded in multi-byte items,
|
|
without removing visible labels.</p>
|
|
|
|
|
|
<h3 id="toggle-data">Toggle Data Scan</h3>
|
|
|
|
<p>This menu item is in the Edit menu, and acts as a shortcut to opening
|
|
the Project Properties editor, and clicking on the <samp>Analyze
|
|
Uncategorized Data</samp> checkbox. When enabled, SourceGen will look
|
|
for character strings and regions of identical bytes, and generate
|
|
<code>.STR</code> and <code>.FILL</code> directives. When
|
|
disabled, uncategorized data is presented as one byte per line, which can
|
|
be handy if you're trying to get at a byte in the middle of a string.</p>
|
|
<p>As with all other project property changes, this is an undoable
|
|
action.</p>
|
|
|
|
|
|
<h3 id="clipboard">Copying to Clipboard</h3>
|
|
|
|
<p>When you use <samp>Edit > Copy</samp>, all lines selected in the
|
|
code list are copied to the system clipboard. This can be a convenient
|
|
way to post code snippets into forum postings or documentation. The text is
|
|
copied from the data shown on screen, so your chosen capitalization
|
|
and pseudo-ops will appear in the copy.</p>
|
|
<p>Long comments are included, but notes are not.</p>
|
|
<p>By default, only the label, opcode, operand, and comment fields are
|
|
included. From the
|
|
<a href="settings.html#app-settings">app settings</a> dialog you can select
|
|
alternative formats that include additional columns.</p>
|
|
|
|
<p>A copy of all of the fields is also written to the clipboard in CSV
|
|
format. If you have a spreadsheet like Excel, you can use
|
|
<samp>Paste Special</samp> to put the data into individual cells.</p>
|
|
|
|
</div>
|
|
|
|
<div id="footer">
|
|
<p><a href="index.html">Back to index</a></p>
|
|
</div>
|
|
</body>
|
|
<!-- Copyright 2018 faddenSoft -->
|
|
</html>
|