mirror of
https://github.com/fadden/6502bench.git
synced 2024-11-26 21:49:45 +00:00
256 lines
12 KiB
HTML
256 lines
12 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>Editors - 6502bench SourceGen</title>
|
|
</head>
|
|
|
|
<body>
|
|
<div id="content">
|
|
<h1>6502bench SourceGen: Editors</h1>
|
|
<p><a href="index.html">Back to index</a></p>
|
|
|
|
|
|
<h2><a name="address">Edit Address</a></h2>
|
|
<p>This adds a target address directive (".ORG") to the current offset.
|
|
If you leave the text field blank, the directive will be removed.</p>
|
|
<p>Addresses are always interpreted as hexadecimal. You can prefix
|
|
it with a '$', but that's not required.
|
|
24-bit addresses may be written with a bank separator, e.g. "12/3456"
|
|
would resolve to address $123456.</p>
|
|
|
|
<p>There will always be an address directive at the start of the file.
|
|
Attempts to remove it will be ignored.</p>
|
|
|
|
|
|
<h2><a name="flags">Edit Status Flag Override</a></h2>
|
|
<p>The state of the processor status flags are tracked for every
|
|
instruction. Each individual flag is recorded as zero, one, or
|
|
"indeterminate", meaning it could hold either value at the start of
|
|
that instruction. You can override the value of individual flags.</p>
|
|
<p>The 65816 emulation bit, which is not part of the processor status
|
|
register, may also be set in the editor.</p>
|
|
<p>The M, X, and E flags will not be editable unless your CPU configuration
|
|
is set to 65816.</p>
|
|
|
|
|
|
<h2><a name="label">Edit Label</a></h2>
|
|
<p>Sets or clears a label at the selected offset. The label must have
|
|
the proper form, and not have the same name as another symbol. If
|
|
you edit an auto-generated label you will be required to change the name.</p>
|
|
<p>The label may be marked as local, global, or global and exported.
|
|
Local labels may be modified by the assembly code generator to have a more
|
|
convenient form, such as a local loop identifier. Global labels are
|
|
always output as-is. Exported labels are added to a table that may
|
|
be imported by other projects (see
|
|
<a href="advanced.html#multi-bin">Working With Multiple Binaries</a>).</p>
|
|
|
|
|
|
<h2><a name="operand">Edit Instruction Operand</a></h2>
|
|
<p>Operands can be displayed in a variety of numeric formats, or as a
|
|
symbol. The ASCII character format is only available for operands
|
|
whose value falls into the range of low- or high-ASCII characters.</p>
|
|
<p>Symbols may be used in their entirety, or shifted and masked.
|
|
The low / high / bank selector determines which byte is used as the
|
|
low byte. For 16-bit operands, this acts as a shift rather than a byte
|
|
select. If the symbol is wider than the operand field, a mask will be
|
|
applied automatically.</p>
|
|
|
|
<p>A few shortcuts are provided when specifying a symbol. As noted in
|
|
the introductory sections, operand symbols are weak references. If the
|
|
symbol hasn't been defined as a label yet, the operand will be formatted
|
|
as hex, which is probably not what you want.</p>
|
|
<p>The default behavior is just to set the operand's symbol.</p>
|
|
<p>For operands that target an offset inside the file, if the target
|
|
address does not yet have a label, and the symbol doesn't exist, you may
|
|
set the symbol as the label on the target address as well. You can do
|
|
this in addition to setting the operand symbol, or in lieu of setting the
|
|
operand symbol. (You will often want to only create the label, and let
|
|
SourceGen convert the numeric reference to a symbolic reference
|
|
automatically.) If you select the "set label instead" option, and the
|
|
operand already had a symbol reference defined, the operand's format will
|
|
be set to default.</p>
|
|
<p>For operands that target an external address, if the symbol doesn't
|
|
exist, you can ask the editor to create a project symbol with the
|
|
appropriate label and address value. The operand symbol will also be set.</p>
|
|
|
|
<p>The <code>MVN</code> and <code>MVP</code> instructions on the 65816
|
|
are a bit peculiar, because they have two operands rather than one.
|
|
SourceGen currently only allows you to set one format, which will be
|
|
applied to both operands. If you specify a symbol, the symbol will
|
|
be used twice, adjusted if necessary. (This may be addressed in a
|
|
future release.)</p>
|
|
|
|
|
|
<h2><a name="data">Edit Data Format</a></h2>
|
|
<p>This dialog offers a variety of choices, and can be used to apply a
|
|
format to a range of offsets. You must select all of the bytes you want
|
|
to format. For example, to format two bytes as a 16-bit word, you must
|
|
select both bytes in the editor. (If you click on the first item, then
|
|
Shift+double-click on the operand field of the last item, you can do
|
|
this very quickly.) The selection does not need to be contiguous: you
|
|
can use Control+click to select scattered items.)</p>
|
|
<p>If the range is discontiguous, or crosses a visual boundary
|
|
such as a change in address, a user-specified label, or a long comment
|
|
or note, the selection will be split into smaller regions. A message at the
|
|
top of the dialog indicates how many bytes have been selected, and how
|
|
many regions they have been divided into.</p>
|
|
<p>(End-of-line comments do <i>not</i> split a region, and will
|
|
disappear if they end up inside a multi-byte data item.)</p>
|
|
|
|
<p>The "Simple Data" items behave the same as their equivalents in the
|
|
Edit Operand dialog. However, because the width is not determined by
|
|
an instruction opcode, and multiple items can be selected, you will need
|
|
to specify how wide each item is and what its byte order is. For data
|
|
you also have the option of setting the format to "Address", which marks
|
|
the selected bytes as a numeric reference.</p>
|
|
|
|
<p>Consider a simple example: suppose you find a table of 16-bit
|
|
addresses in the code. Click on
|
|
the first byte, shift-click the last byte, then select the Edit Data menu
|
|
item. The number of bytes selected should be even. Select
|
|
"16-bit words, little-endian", then over to the right click on
|
|
"Address". When you click OK, the selected data will be formatted as a
|
|
series of 16-bit address values. If the addresses can be resolved inside
|
|
the data file, each address will be assigned a label.</p>
|
|
|
|
<p>The "Bulk Data" items can represent large chunks of data compactly.
|
|
The "fill" option is only available if all selected bytes have the
|
|
same value.</p>
|
|
|
|
<p>The "String" items are enabled or disabled depending on whether the
|
|
data you have selected is in the appropriate format. For example,
|
|
"Null-terminated strings" is only enabled if the data is exclusively
|
|
ASCII characters followed by $00. Zero-length strings are allowed,
|
|
but only if some non-zero-length strings are present.</p>
|
|
<p>Standard ASCII and "high ASCII" are both supported, but strings must
|
|
be composed exclusively of one or the other.</p>
|
|
|
|
<p>To avoid burying a label in the middle of a data item, contiguous areas
|
|
are split at labels. This can sometimes have unexpected effects. For
|
|
example, this can be formatted as two 16-bit words or one 32-bit word:</p>
|
|
<pre>
|
|
.DD1 $01
|
|
.DD1 $ef
|
|
.DD1 $01
|
|
.DD1 $f0
|
|
</pre>
|
|
|
|
<p>With a label in the middle, it be formatted as two 16-bit words, but
|
|
not as a 32-bit word:</p>
|
|
<pre>
|
|
.DD1 $01
|
|
.DD1 $ef
|
|
LABEL .DD1 $01
|
|
.DD1 $f0
|
|
CODE LDA LABEL
|
|
</pre>
|
|
|
|
<p>If this is inconvenient, you can add a label at a 32-bit boundary, and
|
|
reference that instead:</p>
|
|
<pre>
|
|
LABEL .DD1 $01
|
|
.DD1 $ef
|
|
.DD1 $01
|
|
.DD1 $f0
|
|
CODE LDA LABEL+2
|
|
</pre>
|
|
|
|
<p>With the label out of the way, the data can be formatted as desired.</p>
|
|
|
|
|
|
<h2><a name="comment">Edit Comment</a></h2>
|
|
<p>NOTE: the shortcut for Edit Comment is Ctrl+; (semicolon). For some
|
|
reason Windows likes to show this as "Ctrl+Oem1".</p>
|
|
|
|
<p>Enter an end-of-line (EOL) comment, or leave the text field blank to
|
|
delete it. EOL comments may be placed on instruction and data lines, but
|
|
not on assembler directives.</p>
|
|
<p>It's wise to restrict comments to the ASCII character set, because
|
|
not all assemblers can accept UTF-8 input. Code generators for such
|
|
assemblers will convert non-ASCII characters to '?' or something similar.
|
|
If this isn't a concern, you can enter any characters you like.</p>
|
|
<p>There is no fixed limit on the number of characters, but you may
|
|
want to limit the overall length if you're hoping to create 80-column
|
|
output. Some retro assemblers may have hard line length limitations,
|
|
which could result in the comment being truncated in generated sources.</p>
|
|
<p>A semicolon (';') is placed at the start of the line. If an assembler
|
|
has different conventions, a different delimiter character may be used. You
|
|
don't need to include a semicolon in the comment field.</p>
|
|
|
|
<p>Comments on platform symbols are read from the platform symbol file, and
|
|
cannot be edited from within SourceGen. Comments on project symbols are
|
|
stored in the project file, and can be edited with the project symbol
|
|
editor.</p>
|
|
|
|
|
|
<h2><a name="long-comment">Edit Long Comment</a></h2>
|
|
<p>Long comments can be arbitrarily long and span multiple lines. They
|
|
will be word-wrapped at a line width of your choosing. They're always
|
|
drawn with a fixed-width font, so you can create ASCII-art diagrams.
|
|
Comment delimiters are added automatically at the start of each line.</p>
|
|
<p>For a true retro look you can "box" the comment with asterisks. You
|
|
can create a full-width row of asterisks by putting a '*' on a line by
|
|
itself. (Assembly source generators are allowed to use a character
|
|
other than '*' for the output, e.g. they might use a full set of
|
|
box outline characters, though that's somewhat against the spirit of
|
|
the thing. Regardless, a solo '*' results in a line.)</p>
|
|
<p>The bottom window will update automatically as you type, showing what
|
|
the output is expected to look like. The actual assembler source output
|
|
will depend on features of the target assembler, such as comment
|
|
delimiter choices and maximum line length limitations. For example,
|
|
Merlin allows a leading '*' to indicate a comment, while cc65 does not,
|
|
so cc65 code uses ";*' instead. Because the length limitation affects
|
|
the length of the line, not just the comment text, an asterisk-boxed
|
|
comment will have one fewer character per line in cc65 output.</p>
|
|
|
|
<p>Clear the text field to delete the comment.</p>
|
|
<p>You can use Ctrl+Enter as a keyboard shortcut for "OK".</p>
|
|
|
|
<p>The long comment at the very top of the project is special, as it's
|
|
not associated with a file offset. If you delete it, you can get it
|
|
back by using Edit > Edit Header Comment.</p>
|
|
|
|
|
|
<h2><a name="note">Edit Note</a></h2>
|
|
<p>Notes are similar to long comments, in that they can be arbitrarily
|
|
long and span multiple lines. However, because they're never included
|
|
in generated output, options like line width formatting and boxing
|
|
aren't relevant.</p>
|
|
<p>Instead, you can select a highlight color for the note to make it
|
|
stand out. You may want to assign certain colors to specific things,
|
|
e.g. blue for "I don't know what this is" or green for "this is a
|
|
bookmark for the really interesting stuff". The color will be applied
|
|
to the note in the code list and in the "Notes" window.</p>
|
|
|
|
<p>Clear the text field to delete the note.</p>
|
|
<p>You can use Ctrl+Enter as a keyboard shortcut for "OK".</p>
|
|
|
|
|
|
<h2><a name="project-symbol">Edit Project Symbol</a></h2>
|
|
<p>This is used to edit the properties of a project symbol.</p>
|
|
<p>The label must meet the criteria for symbols (see
|
|
<a href="intro.html#about-symbols">All About Symbols</a>), and must
|
|
not have the same name as another project symbol. It can overlap
|
|
with platform symbols and user labels.</p>
|
|
<p>The value may be entered in decimal, hexadecimal, or binary. The
|
|
base you choose will be remembered, so that the value will be displayed
|
|
the same way when used in a .EQ directive.</p>
|
|
<p>If you enter a comment, it will be placed at the end of the line of
|
|
the .EQ directive.</p>
|
|
<p>Symbols marked as "address" will be applied automatically when an
|
|
operand references an address outside the scope of the data file. Symbols
|
|
marked as "constant" will not, though you can still specify them manually.</p>
|
|
|
|
</div>
|
|
|
|
<div id="footer">
|
|
<p><a href="index.html">Back to index</a></p>
|
|
</div>
|
|
</body>
|
|
<!-- Copyright 2018 faddenSoft -->
|
|
</html>
|