1
0
mirror of https://github.com/fadden/6502bench.git synced 2024-12-11 13:50:13 +00:00
6502bench/SourceGen/RuntimeData/Help/editors.html

258 lines
12 KiB
HTML
Raw Normal View History

2018-09-28 17:05:11 +00:00
<!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>
2018-10-09 17:04:10 +00:00
<div id="content">
2018-09-28 17:05:11 +00:00
<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.
2018-10-04 01:03:04 +00:00
If you leave the text field blank, the directive will be removed.</p>
2018-09-28 17:05:11 +00:00
<p>Addresses are always interpreted as hexadecimal. You can prefix
2018-10-04 01:03:04 +00:00
it with a '$', but that's not required.
24-bit addresses may be written with a bank separator, e.g. "12/3456"
2018-09-28 17:05:11 +00:00
would resolve to address $123456.</p>
2018-10-04 01:03:04 +00:00
<p>There will always be an address directive at the start of the file.
2018-09-28 17:05:11 +00:00
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
2018-10-04 01:03:04 +00:00
is set to 65816.</p>
2018-09-28 17:05:11 +00:00
<h2><a name="label">Edit Label</a></h2>
<p>Sets or clears a label at the selected offset. The label must have
2018-10-30 22:42:13 +00:00
the
<a href="intro.html#about-symbols">proper form</a>, 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>
2018-09-28 17:05:11 +00:00
<p>The label may be marked as local, global, or global and exported.
2018-10-04 01:03:04 +00:00
Local labels may be modified by the assembly code generator to have a more
2018-09-28 17:05:11 +00:00
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>
2018-09-28 17:05:11 +00:00
<h2><a name="operand">Edit Instruction Operand</a></h2>
2018-09-28 17:05:11 +00:00
<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>
2018-10-04 01:03:04 +00:00
<p>Symbols may be used in their entirety, or shifted and masked.
2018-09-28 17:05:11 +00:00
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
2018-10-04 01:03:04 +00:00
select. If the symbol is wider than the operand field, a mask will be
applied automatically.</p>
2018-09-28 17:05:11 +00:00
<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>
2018-10-04 01:03:04 +00:00
<p>The default behavior is just to set the operand's symbol.</p>
2018-09-28 17:05:11 +00:00
<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
2018-10-04 01:03:04 +00:00
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
2018-10-09 17:04:10 +00:00
can use Control+click to select scattered items.)</p>
2018-10-04 01:03:04 +00:00
<p>If the range is discontiguous, or crosses a visual boundary
2018-09-28 17:05:11 +00:00
such as a change in address, a user-specified label, or a long comment
2018-10-04 01:03:04 +00:00
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>
2018-09-28 17:05:11 +00:00
<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
2018-10-04 01:03:04 +00:00
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
2018-09-28 17:05:11 +00:00
the first byte, shift-click the last byte, then select the Edit Data menu
item. The number of bytes selected should be even. Select
2018-10-04 01:03:04 +00:00
"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>
2018-09-28 17:05:11 +00:00
<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>
2018-09-28 17:05:11 +00:00
<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
2018-10-04 01:03:04 +00:00
has different conventions, a different delimiter character may be used. You
don't need to include a semicolon in the comment field.</p>
2018-09-28 17:05:11 +00:00
<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
2018-10-04 01:03:04 +00:00
can create a full-width row of asterisks by putting a '*' on a line by
2018-09-28 17:05:11 +00:00
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
2018-10-04 01:03:04 +00:00
the thing. Regardless, a solo '*' results in a line.)</p>
2018-09-28 17:05:11 +00:00
<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 &gt; 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
2018-10-04 01:03:04 +00:00
marked as "constant" will not, though you can still specify them manually.</p>
2018-09-28 17:05:11 +00:00
</div>
2018-10-09 17:04:10 +00:00
<div id="footer">
2018-09-28 17:05:11 +00:00
<p><a href="index.html">Back to index</a></p>
</div>
</body>
<!-- Copyright 2018 faddenSoft -->
</html>