mirror of
https://github.com/fadden/6502bench.git
synced 2024-10-31 19:04:44 +00:00
fca742e890
Added the recovery file check when a project is opened, and the GUI elements for choosing which file to use. If a recovery file exists but can't be opened, presumably because it's open by another process, offer to open the project read-only. (This is a generally good idea, but we don't hold the project file open in normal usage, so it only works when auto-save is enabled.) After making a choice, auto-save is disabled until the first manual save. One thing we don't do: if we find a recovery file, but auto-save is disabled, the recovery file won't be deleted after the user makes a choice. This might be a feature. Updated documentation. (issue #161)
711 lines
35 KiB
HTML
711 lines
35 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 application will ask you to save the new project to a file.
|
|
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. (You can cancel the dialog to proceed
|
|
without creating a project file, but certain features will be unavailable.)</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="saving">Saving a Project</h2>
|
|
|
|
<p>You can save your project with <samp>File > Save</samp>, or by
|
|
hitting <kbd class="key">Ctrl+S</kbd>. To save the project to a different
|
|
file, use <samp>File > Save As</samp>, but bear in mind that the data
|
|
file is expected to have the same name as the project file, minus the
|
|
".dis65" extension.</p>
|
|
|
|
<p>If auto-save is enabled in the application settings, a "recovery" file
|
|
will be created and updated periodically. This file has the same name as
|
|
the project file, but with "_rec" added. The recovery file is only updated
|
|
if the project has been edited but not saved, and the auto-save timer is reset
|
|
whenever the project is manually saved, so if you're diligent about saving
|
|
your work the file may never be written to.</p>
|
|
|
|
<p>When a project is opened, if a recovery file exists, the file will be
|
|
checked to see if it's empty or open in a different process. In the former
|
|
case it will be ignored, in the latter you will be asked if you want to
|
|
open the project read-only. If the file is non-empty and not in use, you
|
|
will be given the opportunity to choose which file to use. After making a
|
|
choice, the auto-save feature will be disabled until the first manual save
|
|
is made.</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>
|