1
0
mirror of https://github.com/fadden/6502bench.git synced 2024-12-11 13:50:13 +00:00
6502bench/SourceGen/RuntimeData/Help/mainwin.html
Andy McFadden 97a372a884 Add selectable auto-label styles
SourceGen creates "auto" labels when it finds a reference to an
address that doesn't have a label associated with it.  The label for
address $1234 would be "L1234".  This change allows the project to
specify alternative label naming conventions, annotating them with
information from the cross-reference data.  For example, a subroutine
entry point (i.e. the target of a JSR) would be "S_1234".  (The
underscore was added to avoid confusion when an annotation letter
is the same as a hex digit.)

Also, tweaked the way the preferred clipboard line format is stored
in the settings file (was an integer, now an enumeration string).
2019-04-15 15:14:04 -07:00

472 lines
22 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>Main Window - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: Main Window</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 &gt; 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 large 65816 programs is
incomplete. The maximum size for a data file is currently 1 MiB.</p>
<p>The first time you save the project (with File &gt; 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 &gt; 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. You will also be given the opportunity
to cancel the loading of 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 &gt; 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 clickable links 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 of the action takes place in the center code list.</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. Always shown as a six-digit hex value
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 in other rows will update
the window 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, 'H' means
one or more bytes has a hint, '#' 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 &#x25bc; 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.</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#operand">Edit Operand</a> or
<a href="editors.html#data">Edit Data Format</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 &gt; Select All. Resize columns by
left-clicking on the divider in the header and dragging it.</p>
<p>Multi-line items, such as long comments or ASCII strings, are
selected as a whole when any part is selected.</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. Enabled when a single instruction or
data line is selected.</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#operand">Edit Operand</a>. Opens the
Edit Instruction Operand or Edit Data Format 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="#hints">Hinting</a> (Hint As Code Entry Point, Hint As
Data Start, Hint As Inline Data, Remove Hints). Enabled when one or more
code and data lines are selected. Remove Hints is only enabled when
at least one line has hints. The keyboard shortcuts for hints are
two-key combinations.</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>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 &amp; Redo</a></h3>
<p>You can undo a change with Edit &gt; Undo, or Ctrl+Z. You can redo a
change with Edit &gt; 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 the buffer.</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. JSR addr, JSL addr)</li>
<li>branch - conditional or unconditional branch (e.g. JMP addr, BCC addr)</li>
<li>read - read from memory (e.g. LDA addr, BIT addr)</li>
<li>write - write to memory (e.g. STA addr)</li>
<li>rmw - read-modify-write (e.g. LSR addr, TSB addr)</li>
<li>ref - address reference only (e.g. LDA #&lt;addr, PEA addr)</li>
<li>data - address referenced by data (e.g. .DD2 addr)</li>
</ul>
<p>In addition, the source will be identified as a symbolic ("Sym") or
numeric ("Num") reference. Most will be symbolic, because SourceGen
generates symbols automatically. However, references to addresses that
are offset from a symbol will also create a numeric reference entry.
For example, "LDA addr+1" will create a symbolic reference at &lt;addr&gt;
(shown in the table with an adjustment of "+1") and a numeric reference
at &lt;addr+1&gt;.</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.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>
<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="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 Edit &gt; Find to search for text. This performs a case-insensitive
text search on the label, opcode, operand, and comment fields.
Use Edit &gt; Find Next to find the next match.</p>
<p>Use Edit &gt; 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.</p>
<p>When you jump around, by double-clicking on an opcode or an entry
in one of the side windows, the currently-selected line is added to
a navigation stack. You can use the arrows on the toolbar to navigate
forward or backward. (You can use Alt+Left/Right Arrow, or
Ctrl+- / Ctrl+Shift+-, as keyboard shortcuts.)</p>
<h3><a name="hints">Adding and Removing Hints</a></h3>
<p>To add code entry or data hints, select the desired offsets and
use Actions &gt; Hint As Code Entry Point or Hint As Data. Because code
hints mean "the code analyzer should start here", and data hints mean
"the code analyzer should stop here", there is rarely any reason to hint
multiple consecutive bytes. For this reason, only the first byte on each
selected line will be hinted.</p>
<p>For inline data, you need to hint every byte, so every byte in every
selected line is hinted when you select Hint As Inline Data. Similarly,
the Remove Hints menu item will remove hints 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 ASCII 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, apply the hint, then hit it
again to re-enable the string &amp; fill analyzer.</p>
<p>Another approach is to can use the "Toggle Single-Byte Format"
menu item to "flatten" the item.</p>
<h3><a name="split-address">Format Split-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 &lt;func1
.dd1 &lt;func2
.dd1 &lt;func3
jmptabh .dd1 &gt;func1
.dd1 &gt;func2
.dd1 &gt;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>The split-address table formatter helps you associate symbols with the
addresses in the table. To use it, start by selecting the entire table.
In the example above, you would select all 6 bytes. The number of bytes
in each part 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, the formatter will report an error.</p>
<p>With the data selected, open the format dialog with
Actions &gt; 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 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 Bytes: indicate which part of the table holds the low bytes. In
the 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 Bytes: indicate which part of the table 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 Bytes: 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 instructions, check
the "Add code entry hint if needed" box to add a code entry point hint
to anything that isn't already marked as an instruction.</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.</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.</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 hints
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".</p>
<h3><a name="toggle-format">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 Format 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 Format 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">Edit Data Format</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 ASCII 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 &gt; 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, the label, opcode, operand, and comment fields are included.
From the
<a href="settings.html#app-settings">app settings</a> dialog you can select
a different format, "Disassembly", which also includes the address and byte
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>