mirror of https://github.com/fadden/6502bench.git
616 lines
30 KiB
HTML
616 lines
30 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
|
<head>
|
|
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
<link href="main.css" rel="stylesheet" type="text/css" />
|
|
<title>Using SourceGen - 6502bench SourceGen</title>
|
|
</head>
|
|
|
|
<body>
|
|
<div id="content">
|
|
<h1>6502bench SourceGen: Using SourceGen</h1>
|
|
<p><a href="index.html">Back to index</a></p>
|
|
|
|
<h2><a name="starting-new">Starting a New Project</a></h2>
|
|
|
|
<p>Select File > New, or if no project is open, click "Start new project".
|
|
This opens the Create New Project 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 "[placeholder]", it
|
|
means that the system doesn't yet have a set of symbols defined for it.)</p>
|
|
|
|
<p>Next, click the "Select File..." button. Pick the file you wish to
|
|
disassemble. The dialog will update with the pathname and some notes
|
|
about the file's size. Click "OK" 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 File > Save), you will be
|
|
prompted for the project name. It's best to use the data file's name
|
|
with ".dis65" 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><a name="opening">Opening an Existing Project</a></h2>
|
|
|
|
<p>Select File > Open, or if no project is open, click "Open
|
|
existing project". 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
|
|
File > Recent Projects. If no project is open, links to the two
|
|
most-recently-opened projects will be available.</p>
|
|
|
|
|
|
<h2><a name="working">Working With a Project</a></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>
|
|
|
|
|
|
<h3><a name="code-list">Code List</a></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 Edit > Select All. 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 Actions 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#address">Set Address</a>. Sets the
|
|
target address at that offset. When multiple lines are selected,
|
|
the target addresses at the start and end of the range is set.
|
|
Enabled when the first line selected is code, data, or an address
|
|
override, and the full selected range does not overlap with another
|
|
address override.</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#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#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#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#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>
|
|
|
|
<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>
|
|
|
|
<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>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><a name="undo">Undo & Redo</a></h3>
|
|
|
|
<p>You can undo a change with Edit > Undo, or Ctrl+Z. You can redo a
|
|
change with Edit > Redo, Ctrl+Y, or Ctrl+Shift+Z.</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><a name="references">References Window</a></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 "Sym" or "Oth" 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 "Sym" (to indicate that the symbol at the selected
|
|
line was referenced) or "Oth" (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><a name="notes">Notes Window</a></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><a name="symbols">Symbols Window</a></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.</p>
|
|
|
|
<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><a name="info">Info Window</a></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>
|
|
|
|
|
|
<h3><a name="messages">Messages Window</a></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>Unresolved weak ref: a reference to a non-existent symbol was found.</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>
|
|
</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 "Hide" button to the left of the messages.
|
|
Un-hide the list by clicking on the "N messages" button at the bottom-right
|
|
corner of the application window.</p>
|
|
|
|
|
|
<h3><a name="navigation">Navigation</a></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 PgUp/PgDn and the arrow keys.</p>
|
|
|
|
<p>Use Navigate > Find to search for text. This performs a case-insensitive
|
|
text search on the label, opcode, operand, and comment fields.
|
|
Use Navigate > Find Next to find the next match, and
|
|
Navigate > Find Previous 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 Navigate > Go To 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
|
|
Navigate > Jump to Operand. 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,
|
|
Navigate > Go to Last Change 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 Navigate > Nav Forward and
|
|
Navigate > Nav Backward 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 Alt+Left/Right Arrow, or
|
|
Ctrl+- / Ctrl+Shift+-, as keyboard shortcuts.)</p>
|
|
|
|
|
|
<h3><a name="atags">Adding and Removing Analyzer Tags</a></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 Actions > Tag Address As Code Start Point (or Stop Point). 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, you need to cover the entire range, so every byte in every
|
|
selected line is tagged when you select Tag Bytes As Inline Data. Similarly,
|
|
the Remove Analyzer Tags menu item will remove tags from every byte.</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 .STR and .FILL ops for you). You can do this
|
|
from the
|
|
<a href="settings.html#project-properties">project properties</a> editor,
|
|
or simply by hitting Ctrl+D. 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 "Toggle Single-Byte Format"
|
|
menu item to "flatten" the item.</p>
|
|
|
|
|
|
<h3><a name="address-table">Format Address Table</a></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 RTS call.</p>
|
|
|
|
<p>While the .dd2 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
|
|
Actions > Format Split-Address Table. 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 "Parts are split
|
|
across sub-tables" box. If the address parts are being pushed
|
|
on the stack for an RTS/RTL, check the "Adjusted for RTS/RTL" 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 "first part of selection". If they were
|
|
stored the other way around, you would click "second part" 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 "Constant", 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 "Nth part of
|
|
selection", 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 "Constant" field to specify the data bank.</li>
|
|
<li>Options: if the table holds the addresses of executable code, check
|
|
the "Tag targets as code start points" 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 "(+)", 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><a name="toggle-single">Toggle Single-Byte Format</a></h3>
|
|
|
|
<p>The "Toggle Single-Byte Format" 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 "Single bytes" displayed as hex, or
|
|
selecting "Default".</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><a name="format-as-word">Format As Word</a></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 .FILLs 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><a name="toggle-data">Toggle Data Scan</a></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 "Analyze Uncategorized
|
|
Data" checkbox. When enabled, SourceGen will look for character strings and
|
|
regions of identical bytes, and generate .STR and .FILL 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><a name="clipboard">Copying to Clipboard</a></h3>
|
|
|
|
<p>When you use Edit > Copy, 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 Paste Special
|
|
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>
|