6502/6502bench
1
0
Fork 0
mirror of https://github.com/fadden/6502bench.git synced 2025-02-27 19:29:08 +00:00
Code Issues Projects Releases Wiki Activity

Rework tutorial for changes in v1.8

Browse Source 
Biggest changes were to the address region handling in Tutorial1
and the use of StdInline.cs for the inline strings in Tutorial4.

Also, fixed the off-by-one error in Tutorial1.
This commit is contained in:
Andy McFadden 2021-11-14 09:02:53 -08:00
parent 713bb74cc0
commit 4537f24958
59 changed files with 349 additions and 545 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
SourceGen/Examples/Tutorial/InlineL1String.cs
View File

@ -1,77 +0,0 @@
// Copyright 2019 faddenSoft. All Rights Reserved.
// See the LICENSE.txt file for distribution terms (Apache 2.0).
using System;
using System.Collections.Generic;
using PluginCommon;
namespace ExtensionScriptSample {
/// <summary>
/// Sample class for handling a JSR followed by a string prefixed with a 1-byte length.
/// </summary>
public class InlineL1String: MarshalByRefObject, IPlugin, IPlugin_SymbolList,
IPlugin_InlineJsr {
private IApplication mAppRef;
private byte[] mFileData;
// Only one label.
private const string CALL_LABEL = "PrintInlineL1String";
private int mInlineL1StringAddr; // jsr
public string Identifier {
get {
return "Inline L1 ASCII string handler";
}
}
public void Prepare(IApplication appRef, byte[] fileData, AddressTranslate addrTrans) {
mAppRef = appRef;
mFileData = fileData;
mAppRef.DebugLog("InlineL1String(id=" +
AppDomain.CurrentDomain.Id + "): prepare()");
}
public void Unprepare() {
mAppRef = null;
mFileData = null;
}
public void UpdateSymbolList(List<PlSymbol> plSyms) {
// reset this every time, in case they remove the symbol
mInlineL1StringAddr = -1;
foreach (PlSymbol sym in plSyms) {
if (sym.Label == CALL_LABEL) {
mInlineL1StringAddr = sym.Value;
break;
}
}
mAppRef.DebugLog(CALL_LABEL + " @ $" + mInlineL1StringAddr.ToString("x6"));
}
public bool IsLabelSignificant(string beforeLabel, string afterLabel) {
return beforeLabel == CALL_LABEL || afterLabel == CALL_LABEL;
}
public void CheckJsr(int offset, int operand, out bool noContinue) {
noContinue = false;
if (operand != mInlineL1StringAddr) {
return;
}
if (offset + 3 >= mFileData.Length) {
return; // length byte is off end
}
int len = mFileData[offset + 3]; // first byte past JSR
if (offset + 4 + len > mFileData.Length) {
mAppRef.DebugLog("L1 string ran off end of file at +" +
(offset + 4).ToString("x6"));
return;
}
// Assuming ASCII. This can be hard-coded, use auto-detection, or look
// up a value in a project constant.
mAppRef.SetInlineDataFormat(offset + 3, len + 1,
DataType.StringL8, DataSubType.Ascii, null);
}
}
}

153
SourceGen/Examples/Tutorial/InlineMulti.cs
View File

@ -1,153 +0,0 @@
// Copyright 2021 faddenSoft. All Rights Reserved.
// See the LICENSE.txt file for distribution terms (Apache 2.0).
using System;
using System.Collections.Generic;
using PluginCommon;
namespace ExtensionScriptSample {
/// <summary>
/// Formats three different kinds of inline functions:
///
/// PrintInlineL1String: format following data as L1 string
/// PrintInlineNullString*: format following data as null-term string.
/// PrintInlineAddrString*: format following data as 16-bit pointer to null-term string.
/// </summary>
public class InlineMultiData : MarshalByRefObject, IPlugin, IPlugin_SymbolList,
IPlugin_InlineJsr {
private IApplication mAppRef;
private byte[] mFileData;
private AddressTranslate mAddrTrans;
private const string L1STR_NAME = "PrintInlineL1String";
private const string NULLSTR_PREFIX = "PrintInlineNullString";
private const string ADDRSTR_PREFIX = "PrintInlineAddrString";
private enum InlineKind { Unknown = 0, L1Str, NullStr, AddrStr };
private Dictionary<int, InlineKind> mInlineLabels = new Dictionary<int, InlineKind>();
public string Identifier {
get {
return "Inline multi-data formatter";
}
}
public void Prepare(IApplication appRef, byte[] fileData, AddressTranslate addrTrans) {
mAppRef = appRef;
mFileData = fileData;
mAddrTrans = addrTrans;
mAppRef.DebugLog("InlineMultiData(id=" +
AppDomain.CurrentDomain.Id + "): prepare()");
}
public void Unprepare() {
mAppRef = null;
mFileData = null;
mAddrTrans = null;
}
public void UpdateSymbolList(List<PlSymbol> plSyms) {
mInlineLabels.Clear();
// Find matching symbols. Save the symbol's value (its address) and the type.
// We want an exact match on L1STR_NAME, and prefix matches on the other two.
foreach (PlSymbol sym in plSyms) {
if (sym.Label.Equals(L1STR_NAME)) {
mInlineLabels.Add(sym.Value, InlineKind.L1Str);
} else if (sym.Label.StartsWith(NULLSTR_PREFIX)) {
mInlineLabels.Add(sym.Value, InlineKind.NullStr);
} else if (sym.Label.StartsWith(ADDRSTR_PREFIX)) {
mInlineLabels.Add(sym.Value, InlineKind.AddrStr);
}
}
mAppRef.DebugLog("Found matches for " + mInlineLabels.Count + " labels");
}
public bool IsLabelSignificant(string beforeLabel, string afterLabel) {
return DoesLabelMatch(beforeLabel) || DoesLabelMatch(afterLabel);
}
private static bool DoesLabelMatch(string label) {
return (label.Equals(L1STR_NAME) ||
label.StartsWith(NULLSTR_PREFIX) ||
label.StartsWith(ADDRSTR_PREFIX));
}
public void CheckJsr(int offset, int operand, out bool noContinue) {
noContinue = false;
InlineKind kind;
if (!mInlineLabels.TryGetValue(operand, out kind)) {
return;
}
switch (kind) {
case InlineKind.L1Str:
// Length-delimited ASCII string
FormatL1String(offset + 3);
break;
case InlineKind.NullStr:
// Null-terminated ASCII string.
FormatNullTermString(offset + 3);
break;
case InlineKind.AddrStr:
// Pointer to data. Format as address. Start by confirming next two
// bytes are inside the file bounds.
if (!Util.IsInBounds(mFileData, offset + 3, 2)) {
return;
}
// Format 16-bit value as an address.
mAppRef.SetInlineDataFormat(offset + 3, 2,
DataType.NumericLE, DataSubType.Address, null);
// Now format the string that the address points to. Extract the
// address from the operand.
int strAddr = Util.GetWord(mFileData, offset + 3, 2, false);
// Convert the address to a file offset. Returns -1 if not in file bounds.
int strOff = mAddrTrans.AddressToOffset(offset, strAddr);
// Format it if it's in bounds.
FormatNullTermString(strOff);
break;
}
}
private void FormatL1String(int offset) {
if (offset < 0 || offset >= mFileData.Length) {
return; // length byte is not inside file
}
int len = mFileData[offset];
if (offset + 1 + len > mFileData.Length) {
mAppRef.DebugLog("L1 string ran off end of file at +" +
(offset + 1).ToString("x6"));
return;
}
// Assuming ASCII.
mAppRef.SetInlineDataFormat(offset, len + 1,
DataType.StringL8, DataSubType.Ascii, null);
}
private void FormatNullTermString(int offset) {
if (offset < 0 || offset >= mFileData.Length) {
return; // start is not inside file
}
// search for the terminating null byte
int nullOff = offset;
while (nullOff < mFileData.Length) {
if (mFileData[nullOff] == 0x00) {
break;
}
nullOff++;
}
if (nullOff == mFileData.Length) {
mAppRef.DebugLog("Unable to find end of null-terminated string at +" +
offset.ToString("x6"));
return;
}
// Assuming ASCII.
mAppRef.SetInlineDataFormat(offset, nullOff - offset + 1,
DataType.StringNullTerm, DataSubType.Ascii, null);
}
}
}

81
SourceGen/Examples/Tutorial/InlineNullTermString.cs
View File

@ -1,81 +0,0 @@
// Copyright 2019 faddenSoft. All Rights Reserved.
// See the LICENSE.txt file for distribution terms (Apache 2.0).
using System;
using System.Collections.Generic;
using PluginCommon;
namespace ExtensionScriptSample {
/// <summary>
/// Sample class for handling a JSR followed by an inline null-terminated string. Any
/// label that starts with "PrintLineNullString" is matched.
/// </summary>
public class InlineNullTermString : MarshalByRefObject, IPlugin, IPlugin_SymbolList,
IPlugin_InlineJsr {
private IApplication mAppRef;
private byte[] mFileData;
private const string LABEL_PREFIX = "PrintInlineNullString";
private Dictionary<int, PlSymbol> mNullStringAddrs = new Dictionary<int, PlSymbol>();
public string Identifier {
get {
return "Inline null-terminated ASCII string handler";
}
}
public void Prepare(IApplication appRef, byte[] fileData, AddressTranslate addrTrans) {
mAppRef = appRef;
mFileData = fileData;
mAppRef.DebugLog("InlineNullStringHandler(id=" +
AppDomain.CurrentDomain.Id + "): prepare()");
}
public void Unprepare() {
mAppRef = null;
mFileData = null;
}
public void UpdateSymbolList(List<PlSymbol> plSyms) {
mNullStringAddrs.Clear();
// Find matching symbols.
foreach (PlSymbol sym in plSyms) {
if (sym.Label.StartsWith(LABEL_PREFIX)) {
mNullStringAddrs.Add(sym.Value, sym);
}
}
mAppRef.DebugLog(LABEL_PREFIX + " matched " + mNullStringAddrs.Count + " labels");
}
public bool IsLabelSignificant(string beforeLabel, string afterLabel) {
return beforeLabel.StartsWith(LABEL_PREFIX) || afterLabel.StartsWith(LABEL_PREFIX);
}
public void CheckJsr(int offset, int operand, out bool noContinue) {
noContinue = false;
if (!mNullStringAddrs.ContainsKey(operand)) {
return;
}
// search for the terminating null byte
int nullOff = offset + 3;
while (nullOff < mFileData.Length) {
if (mFileData[nullOff] == 0x00) {
break;
}
nullOff++;
}
if (nullOff == mFileData.Length) {
mAppRef.DebugLog("Unable to find end of null-terminated string at +" +
(offset+3).ToString("x6"));
return;
}
// Assuming ASCII. This can be hard-coded, use auto-detection, or look
// up a value in a project constant.
mAppRef.SetInlineDataFormat(offset + 3, nullOff - (offset + 3) + 1,
DataType.StringNullTerm, DataSubType.Ascii, null);
}
}
}

123
SourceGen/Examples/Tutorial/Source/Tutorial1.S
View File

@ -1,62 +1,61 @@
; Copyright 2018 faddenSoft. All Rights Reserved.
; See the LICENSE.txt file for distribution terms (Apache 2.0).
;
; Assembler: Merlin 32
INPUT equ $3000
OUTPUT equ $0400
org $1000
ldy #END-AFTER
copy lda BEFORE,y
sta AFTER,y
dey
bmi done
bpl copy
dfb $00
stuff asc 'hello!'
done jmp AFTER
BEFORE
org $2000
AFTER
lda INPUT ;expecting 0-3
cmp #4
blt :valid
lda #4 ;error message
:valid asl A
tax
lda stringtab,x ;set load to address
sta _load+1
lda stringtab+1,x
sta _load+2
ldy #12 ;fixed-width strings
_load lda $0000,y ;self-modifying code
ora #$80
sta OUTPUT,y
dey
bpl _load
rts
stringtab
dw string0
dw string1
dw string2
dw string3
dw stringX
dfb $00
string0 asc 'string zero '
string1 asc 'string one '
string2 asc 'string two '
string3 asc 'string three '
stringX asc 'invalid index'
END
; Copyright 2018 faddenSoft. All Rights Reserved.
; See the LICENSE.txt file for distribution terms (Apache 2.0).
;
; Assembler: Merlin 32
INPUT equ $3000
OUTPUT equ $0400
org $1000
ldy #END-AFTER-1
copy lda BEFORE,y
sta AFTER,y
dey
bpl copy
bmi done
dfb $00
stuff asc 'hello!'
done jmp AFTER
BEFORE
org $2000
AFTER
lda INPUT ;expecting 0-3
cmp #4
blt :valid
lda #4 ;error message
:valid asl A
tax
lda stringtab,x ;set load to address
sta _load+1
lda stringtab+1,x
sta _load+2
ldy #12 ;fixed-width strings
_load lda $0000,y ;self-modifying code
ora #$80
sta OUTPUT,y
dey
bpl _load
rts
stringtab
dw string0
dw string1
dw string2
dw string3
dw stringX
dfb $00
string0 asc 'string zero '
string1 asc 'string one '
string2 asc 'string two '
string3 asc 'string three '
stringX asc 'invalid index'
END

BIN
SourceGen/Examples/Tutorial/Tutorial1
View File

Binary file not shown.

2
docs/sgtutorial/about-disasm.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>

2
docs/sgtutorial/address-tables.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>

2
docs/sgtutorial/advanced-topics.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>

12
docs/sgtutorial/digging-deeper.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
@ -166,10 +166,12 @@
<img src="images/t2-1000-setcode.png" alt="t2-1000-setcode"/>
</div>
<div class="grid-item-text">
<p>Since we believe $2000 is the load address for everything that follows,
click on the line with address $1002, select
<samp>Actions &gt; Set Address</samp>, and enter "2000". With that line
still selected, use <samp>Actions &gt; Tag Address As Code Start Point</samp>
<p>Since we currently believe $2000 is the load address for everything
that follows, click on the line with address $1002, select
<samp>Actions &gt; Create/Edit Address Region</samp>, and enter "2000"
for the address. Click <samp>OK</samp>.
With that line still selected, use
<samp>Actions &gt; Tag Address As Code Start Point</samp>
(<kbd class="key">Ctrl+H</kbd> <kbd class="key">Ctrl+C</kbd>) to
tell the analyzer to start looking for code there.</p>
</div>

2
docs/sgtutorial/editing-data.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data" class="active"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>

107
docs/sgtutorial/extension-scripts.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
@ -94,9 +94,9 @@
inline data. We're going to do it a faster way. For this tutorial,
start a new project with the <samp>Generic 6502</samp> profile, and
in the SourceGen Examples/Tutorial directory select "Tutorial4".</p>
<p>We'll need to load scripts from the project directory, so we have to
<!--<p>We'll need to load scripts from the project directory, so we have to
save the project. <samp>File &gt; Save</samp>,
use the default name ("Tutorial4.dis65").</p>
use the default name ("Tutorial4.dis65").</p>-->
</div>
</div>
@ -111,20 +111,23 @@
a script that can handle that, so use
<samp>Edit &gt; Project Properties</samp>, select the
<samp>Extension Scripts</samp> tab, and click
<samp>Add Scripts from Project</samp>. The file
browser opens in the project directory. Select the file
"InlineL1String.cs", click <samp>Open</samp>, then <samp>OK</samp>.</p>
<samp>Add Scripts from Runtime</samp>. The file
browser opens in the RuntimeData directory. Open the
"<samp>Common</samp>" folder, select the file
"<samp>StdInline.cs</samp>", click <samp>Open</samp>,
then <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinel1-src.png" alt="t4-inlinel1-src"/>
<img src="images/t4-stdinline-src.png" alt="t4-stdinline-src"/>
</div>
<div class="grid-item-text">
<p>Nothing happened. If you look at the script with an editor (and you
know some C#), you'll see that it's looking for a <code>JSR</code> to a
function called <code>PrintInlineL1String</code>. So let's give it one.</p>
function that begins with certain prefixes. For ASCII length-delimited
strings, the prefix is <code>InA1_</code>. So let's set a label.</p>
</div>
</div>
@ -146,7 +149,7 @@
<div class="grid-item-text">
<p>This time, double-click the <code>JSR</code> <i>operand</i>
("<samp>L1036</samp>") to edit the operand.
Click <samp>Create Label</samp>, and enter <kbd>PrintInlineL1String</kbd>.
Click <samp>Create Label</samp>, and enter <kbd>InA1_PrintString</kbd>.
Remember that labels are case-sensitive;
you must enter it exactly as shown. Hit <samp>OK</samp> to accept the label,
and <samp>OK</samp> to close the operand editor.</p>
@ -160,27 +163,9 @@
<div class="grid-item-text">
<p>If all went well, address $1003
should now be an L1 string "<code>How long?</code>", and address $100D
should be another <code>JSR</code>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The next <code>JSR</code> appears to be followed by a null-terminated string, so
we'll need something that handles that.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinenull-src.png" alt="t4-inlinenull-src"/>
</div>
<div class="grid-item-text">
<p>Go back into Project Properties
and add the script called "InlineNullTermString.cs" from the project directory.
This script is slightly different, in that it handles any <code>JSR</code> to a label
that starts with <code>PrintInlineNullString</code>. So let's give it a couple of
those.</p>
should be another <code>JSR</code>. This one appears to be followed
by an inline null-terminated string, so we'll need something
that handles that.</p>
</div>
</div>
@ -191,39 +176,11 @@
<div class="grid-item-text">
<p>Double-click the operand on line $100D ("<code>L1037</code>"),
click <samp>Create Label</samp>,
and set the label to "<kbd>PrintInlineNullStringOne</kbd>".
and set the label to "<kbd>InAZ_PrintString1</kbd>".
Hit <samp>OK</samp> twice. That formatted the first one and got us
to the next <code>JSR</code>. Repeat the process on line $1019
("<code>L1038</code>"), setting the label to "<kbd>PrintInlineNullStringTwo</kbd>".</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinemulti-before.png" alt="t4-inlinemulti-before"/>
</div>
<div class="grid-item-text">
<p>Things are looking good, but we've got one left, and it's got a
twist. Instead of a string, the <code>JSR</code> at $1025 is followed by a
pointer to a string. We'd like to format the pointer as an address,
and then format the string it points to.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinemulti-src.png" alt="t4-inlinemulti-src"/>
</div>
<div class="grid-item-text">
<p>We're going to add a third extension script. Sometimes it's
convenient to collect all inline data handlers for a project into a
single script, so we'll demonstrate that here. The new script handles
the previous two cases as well as this new case.
Go into Project
Properties, click the Extension Scripts tab, select the two scripts
you added earlier, and click Remove. Then add the script "InlineMulti.cs"
from the project directory. Click <samp>OK</samp> twice. Note that
the strings formatted earlier remain formatted.</p>
to the next <code>JSR</code>, at $1019. Repeat the process on line $1019
("<code>L1038</code>"), setting the label to
"<kbd>InAZ_PrintString2</kbd>".</p>
</div>
</div>
@ -232,18 +189,19 @@
<img src="images/t4-inlinemulti-done.png" alt="t4-inlinemulti-done"/>
</div>
<div class="grid-item-text">
<p>Double-click the operand on line $1025 ("<code>L1039</code>"),
click <samp>Create Label</samp>,
and set the label to "<kbd>PrintInlineAddrString</kbd>".
Hit <samp>OK</samp> twice. This formatted the address at $1028,
and also formatted the string at $102b as a null-terminated string.
<p>The last <code>JSR</code>, at $1025, is followed by a 16-bit
pointer. Edit the operand, and use <samp>Create Label</samp> to
set the label at the target address to "<kbd>InWA_StringPtr</kbd>".
Because the bytes were formatted as an address and not a just a
16-bit value, a label was generated automatically.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>What we'd really like to do in this case is to have it format the
16-bit address as a pointer, and format the data it points to as
a null-terminated string. The StdInline script doesn't know how to
do that though, so you'd need to write a custom script. (Scripts
can format multiple data items, add symbolic references to labels
and constants, and chase pointers around.)</p>
<p>The entire project is now nicely formatted. In a real project the
"Print Inline" locations would be actual print functions, not just <code>RTS</code>
instructions. There would likely be multiple <code>JSR</code>s to the print function,
@ -251,9 +209,14 @@
strings and clean up the disassembly automatically. The reason for
allowing wildcard names is that some functions may have multiple
entry points or chain through different locations.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Extension scripts can make your life much easier, but they do require
some programming experience. See the SourceGen manual for more details.</p>
some programming experience. See the "Advanced Topics" section in the
SourceGen manual for more details.</p>
</div>
</div>

2
docs/sgtutorial/generating-code.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code" class="active"><a href="generating-code.html">Generating Code</a></li>

BIN
docs/sgtutorial/images/t1-1000-comment.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.3 KiB

BIN
docs/sgtutorial/images/t1-2003-done.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 8.3 KiB

BIN
docs/sgtutorial/images/t1-addr-chg-1017.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 14 KiB

BIN
docs/sgtutorial/images/t1-all-columns.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 22 KiB

BIN
docs/sgtutorial/images/t1-asmgen-asmout.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 19 KiB

BIN
docs/sgtutorial/images/t1-asmgen-preview.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 19 KiB

BIN
docs/sgtutorial/images/t1-click-1002.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 51 KiB

After

Width:  |  Height:  |  Size: 71 KiB

BIN
docs/sgtutorial/images/t1-click-1017.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 28 KiB

After

Width:  |  Height:  |  Size: 44 KiB

BIN
docs/sgtutorial/images/t1-code-list-1000.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.3 KiB

BIN
docs/sgtutorial/images/t1-edit-2000-done.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 20 KiB

BIN
docs/sgtutorial/images/t1-pre-sym-2000.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.5 KiB

After

Width:  |  Height:  |  Size: 5.5 KiB

BIN
docs/sgtutorial/images/t1-prelabel-after.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

BIN
docs/sgtutorial/images/t1-prelabel-before.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.0 KiB

BIN
docs/sgtutorial/images/t1-prelabel-edit.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
docs/sgtutorial/images/t1-select-info.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.9 KiB

BIN
docs/sgtutorial/images/t1-set-addr-1017.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 29 KiB

After

Width:  |  Height:  |  Size: 56 KiB

BIN
docs/sgtutorial/images/t1-set-addr-fixed.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 39 KiB

BIN
docs/sgtutorial/images/t1-simple-instr-edit.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 51 KiB

BIN
docs/sgtutorial/images/t1-symbol-filters.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.8 KiB

After

Width:  |  Height:  |  Size: 6.9 KiB

BIN
docs/sgtutorial/images/t2-1000-edit1.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.0 KiB

After

Width:  |  Height:  |  Size: 6.0 KiB

BIN
docs/sgtutorial/images/t2-1000-edit2.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.5 KiB

After

Width:  |  Height:  |  Size: 6.5 KiB

BIN
docs/sgtutorial/images/t2-1000-fmt-word.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.3 KiB

After

Width:  |  Height:  |  Size: 6.3 KiB

BIN
docs/sgtutorial/images/t2-1000-ready.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

BIN
docs/sgtutorial/images/t2-1000-setcode.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.4 KiB

After

Width:  |  Height:  |  Size: 8.5 KiB

BIN
docs/sgtutorial/images/t2-tutorial-top.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 11 KiB

BIN
docs/sgtutorial/images/t4-inlinel1-done.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.2 KiB

After

Width:  |  Height:  |  Size: 8.2 KiB

BIN
docs/sgtutorial/images/t4-inlinel1-edit.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 53 KiB

After

Width:  |  Height:  |  Size: 53 KiB

BIN
docs/sgtutorial/images/t4-inlinel1-src.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.9 KiB

BIN
docs/sgtutorial/images/t4-inlinemulti-before.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 8.5 KiB

BIN
docs/sgtutorial/images/t4-inlinemulti-done.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 25 KiB

After

Width:  |  Height:  |  Size: 25 KiB

BIN
docs/sgtutorial/images/t4-inlinemulti-src.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 4.5 KiB

BIN
docs/sgtutorial/images/t4-inlinenull-done.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 19 KiB

BIN
docs/sgtutorial/images/t4-inlinenull-src.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.1 KiB

BIN
docs/sgtutorial/images/t4-stdinline-src.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.8 KiB

2
docs/sgtutorial/incl-sidenav.html
View File

@ -6,7 +6,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>

2
docs/sgtutorial/index.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>

2
docs/sgtutorial/inline-data.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>

57
docs/sgtutorial/labels-symbols.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols" class="active"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
@ -374,10 +374,63 @@
</div>
<hr style="width:80%;"/>
<h4>Address Region Pre-Labels</h4>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-prelabel-before.png" alt="t1-prelabel-before"/>
</div>
<div class="grid-item-text">
<p>When we created an address region at $2000, the <code>LDA</code>
on line $1002 lost its label, and the <code>STA</code> on line $1005
gained one. The difficulty with having labels in both operands is that
both instructions refer to the byte at offset +000017, but that offset has
different addresses before and after the code is relocated, and you
can't assign multiple addresses to a single file offset.</p>
<p>In assembly source code, we'd solve this by putting a label right
before the address change, and another one after. We can do the same
thing here by setting a "pre-label" for the address region.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-prelabel-edit.png" alt="t1-prelabel-edit"/>
</div>
<div class="grid-item-text">
<p>Select the <code>.addrs</code> line before line $2000, then use
<samp>Actions &gt; Create/Edit Address Region</samp> (or double-click
on the operand of the <code>.addrs</code> line, i.e. "<code>$2000</code>";
if you double-click on the <code>.addrs</code> opcode you'll jump
to the matching <code>.adrend</code> instead).
This opens the address region editor. In the <samp>Pre-label</samp>
section near the bottom, enter "<kbd>COPY_SRC</kbd>", then click
<samp>OK</samp>.
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-prelabel-after.png" alt="t1-prelabel-after"/>
</div>
<div class="grid-item-text">
<p>This added a line before the <code>.addrs $2000</code> with
the new label, and updated the <code>LDA</code> at line $1002 to
refer to the symbol.</p>
<p>Pre-labels are treated as "external" symbols, because the address
they're associated with isn't actually represented by the file in its final
form. As a result, you can't use non-unique local names like
<samp>@LOOP</samp>.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="simple-edits.html" class="btn-previous">&laquo; Previous</a>
<a href="making-edits.html" class="btn-previous">&laquo; Previous</a>
<a href="editing-data.html" class="btn-next">Next &raquo;</a>
</div>

4
docs/sgtutorial/local-variables.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
@ -245,6 +245,8 @@
<hr style="width:80%;"/>
<h4>Showing Cycle Counts</h4>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-enable-counts.png" alt="t2-enable-counts"/>

176
docs/sgtutorial/simple-edits.html → docs/sgtutorial/making-edits.html
View File

@ -12,7 +12,7 @@
<link rel="stylesheet" href="../main.css"/>
<!-- END: /incl-head.html -->
<title>Simple Edits - SourceGen Tutorial</title>
<title>Making Edits - SourceGen Tutorial</title>
</head>
<body>
@ -49,7 +49,7 @@
</div>
<!-- END: /incl-topnav.html -->
<!-- START: incl-sidenav.html active:#sidenav-simple-edits -->
<!-- START: incl-sidenav.html active:#sidenav-making-edits -->
<div id="sidenav">
<!-- side navigation bar contents -->
<ul>
@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits" class="active"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits" class="active"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
@ -83,13 +83,13 @@
<div id="main">
<h2>Simple Edits</h2>
<h2>Making Edits</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>Click the very first line of the file, which is a comment that says
something like "6502bench SourceGen vX.Y.Z". There are three ways to
open the comment editor:</p>
something like "6502bench SourceGen vX.Y.Z". That's not very inspiring,
so let's change it. There are three ways to open the comment editor:</p>
<ol>
<li>Select <samp>Actions &gt; Edit Long Comment</samp> from the menu bar.</li>
<li>Right click, and select <samp>Edit Long Comment</samp> from the
@ -98,7 +98,7 @@
</ol>
<p>Most things in the code list will respond to a double-click.
Double-clicking on addresses, flags, labels, operands, and comments will
open editors for those things. Double-clicking on a value in the "bytes"
open editors for those things. Double-clicking on a value in the "Bytes"
column will open a floating hex dump viewer. This is usually the most
convenient way to edit something: point and click.</p>
</div>
@ -157,23 +157,84 @@
</div>
</div>
<h4>Operands &amp; End-of-Line Comments</h4>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-simple-instr-edit.png" alt="t1-simple-instr-edit"/>
</div>
<div class="grid-item-text">
<p>Select the line with address $1000 ("<code>LDY #$70</code>"), then
<samp>Actions &gt; Edit Operand</samp>. This allows you to pick how you
want the operand to look. It's currently set to <samp>Default</samp>,
which for an 8-bit immediate argument means it's shown as a hexadecimal
value. Click <samp>Decimal</samp>, then <samp>OK</samp>. It now appears
as a decimal value.</p>
<p>You can also open the editor by double-clicking the operand.</p>
<p>If you double-click on a data item, such as the string at $100e,
you will open the Data Operand Editor instead of the Instruction
Operand Editor. (There will be more about this later.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-1000-comment.png" alt="t1-1000-comment"/>
</div>
<div class="grid-item-text">
<p>On the line at $1000, select <samp>Actions &gt; Edit Comment</samp>.
Type a short comment, and hit <kbd class="key">Enter</kbd>. Your
comment appears at the end of the line, in the "comment" column.</p>
<p>You can also open the editor by double-clicking in the comment column.</p>
</div>
</div>
<h4>Address Regions</h4>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-code-list-1000.png" alt="t1-code-list-1000"/>
</div>
<div class="grid-item-text">
<p>Let's take a closer look at the program, which has a short section of
code followed by a bunch of data. The initial code segment is reading
bytes from $1017 and writing them to $2000, using an index register that
starts at 112 ($70) and counts down past zero. That means it's copying
113 ($71) bytes. When the copy is done, execution jumps to the copy of
the code at $2000. It appears to be relocating the next part of the code
before executing it. The disassembler needs to be told about the address
change, which we do with the Address Region Editor.</p>
<p>When defining an address region, there are two ways to go about it.
If you know where the region ends, you can select the entire thing,
and create it with an explicit size. If you're not sure where it
ends, you can create a region with a "floating" end that continues
until it runs into another region or the end of the file. Let's
try it both ways.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-set-addr-1017.png" alt="t1-set-addr-1017"/>
</div>
<div class="grid-item-text">
<p>It's time to do something with the code. If you look at what the code
does you'll see that it's copying several dozen bytes from $1017
to $2000, then jumping to $2000. It appears to be relocating the next
part of the code before
executing it. We want to let the disassembler know what's going on, so
select the line at address $1017 and then
<samp>Actions &gt; Set Address</samp>. (Or double-click on
"<code>1017</code>" in the <samp>Addr</samp> column.)
In the <samp>Set Address</samp> dialog, type "<kbd>2000</kbd>", and hit Enter.)</p>
<p>Select the line at address $1017 and then
<samp>Actions &gt; Create/Edit Address Region</samp>. (Or double-click
on "<code>1017</code>" in the <samp>Addr</samp> column.)
Since we only have one line selected, the address region editor
defaulted to "<samp>Create floating</samp>". It will put the floating
end marker $71 bytes after the start, which happens to be what we
want. (It turns out the tutorial is copying all data to the end of
the file... how convenient.)
In the <samp>Address</samp> field, type "<kbd>2000</kbd>", and click
<samp>OK</samp> (or hit <kbd class="key">Enter</kbd>).</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-addr-chg-1017.png" alt="t1-addr-chg-1017"/>
@ -181,8 +242,9 @@
<div class="grid-item-text">
<p>Note the way the code list has changed. When you changed the address,
the <code>JMP $2000</code> at address $1014 found a home inside
the bounds of the file, so
the code tracer was able to find the instructions there.</p>
the bounds of the file, so the code tracer was able to find the
instructions there. We now have all code and data correctly identified
automatically, without the need to explicitly tag anything.</p>
</div>
</div>
@ -194,35 +256,63 @@
make to the project. (The undo history is <strong>not</strong> saved in
the project file, though, so when you exit the program the history is
lost.)</p>
<p>As you make alterations to the addresses, notice that, while the
<p>Hit <samp>Edit &gt; Undo</samp> one more time, so we're back to
where we were before we added the address region. Let's try creating
it the other way.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-select-info.png" alt="t1-select-info"/>
</div>
<div class="grid-item-text">
<p>Click on line $1017, then scroll to the bottom and shift-click on
the very last line ("<code>.adrend</code>"). (If you prefer to use
keyboard navigation, move to line $1017, then hit
<kbd class="key">Shift+PgDn</kbd> until the selection includes the
end of the file.)
If you look at the Info window in the bottom-right, you should see a
line that says, "<samp>Selection spans 113 ($71) bytes</samp>", which
is what we want.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-set-addr-fixed.png" alt="t1-set-addr-fixed"/>
</div>
<div class="grid-item-text">
<p>Use <samp>Actions &gt; Create/Edit Address Region</samp> to open
the editor.
This time we have selected more than one line, so
"<samp>Create fixed</samp>" is selected by default. Enter
"<kbd>2000</kbd>" in the Address field, and click <samp>OK</samp>.</p>
<p>The results are the same as before. If the region being copied
had been a small part of the file, rather than continuing all the
way to the end, the outcome would have been slightly different.
When an address region with a fixed length ends, the next byte will
be assigned an address based on the <i>previous</i> region. So if
you created a region that mapped addresses $1017-$1046 to $2000-202f,
then the next byte would be at address $1047. This is very useful
for code that relocates small parts of itself, or uses memory
mapping tricks to execute parts of itself at different locations.</p>
</div>
</div>
<h4>Address vs. Offset</h4>
<div class="grid-container">
<div class="grid-item-text">
<p>As you make alterations to the addresses, you will notice that, while the
<samp>Address</samp> column changes, the <samp>Offset</samp> column does not.
File offsets never change, which is why they're shown here and
in the References and Notes windows. (They can, however, be distracting,
so you'll be forgiven if you reduce the offset column width to zero.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-simple-instr-edit.png" alt="t1-simple-instr-edit"/>
</div>
<div class="grid-item-text">
<p>Select the line with address $2003 ("CMP #$04"), then
<samp>Actions &gt; Edit Operand</samp>. This allows you to pick how you want the
operand to look. It's currently set to "Default", which for an 8-bit
immediate argument means it's shown as a hexadecimal value. Click
"Binary", then "OK". It now appears as a binary value.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-2003-done.png" alt="t1-2003-done"/>
</div>
<div class="grid-item-text">
<p>On that same line, select <samp>Actions &gt; Edit Comment</samp>. Type a short
comment, and hit <kbd class="key">Enter</kbd>. Your comment appears
in the "comment" column.</p>
<p>In some cases, such as programs with multiple segments or overlays,
the same address may apply to several different areas. SourceGen fully
supports binaries with overlapping parts.</p>
</div>
</div>

27
docs/sgtutorial/moving-around.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around" class="active"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
@ -169,7 +169,10 @@
<p>Click on L1002 again, then double-click on the opcode ("LDA"). The
selection jumps to L1017. When an operand references an in-file address,
double-clicking on the opcode will take you to it. (Double-clicking on
the operand itself opens a format editor; more on that later.)</p>
the operand itself opens a format editor; more on that later.)
You can accomplish the same thing by selecting the line and hitting
<kbd class="key">Ctrl+J</kbd>, or using
<samp>Jump to Operand</samp> from the <samp>Navigate</samp> menu.</p>
<p>With line L1017 selected, double-click on the line that appears in the
References window. Note the selection jumps to L1002. You can immediately
jump to any reference.</p>
@ -190,11 +193,11 @@
<div class="grid-container">
<div class="grid-item-text">
<p>Select Navigate &gt; Find. Type "hello", and hit Enter. The selection will
move to address $100E, which is a string that says "hello!". You can use
Navigate &gt; Find Next to try to find the next occurrence (there isn't one). You
can search for any text that appears in the rightmost columns (label, opcode,
operand, comment).</p>
<p>Select <samp>Navigate &gt; Find</samp>. Type "hello", and hit Enter. The
selection will move to address $100E, which is a string that says "hello!". You
can use <samp>Navigate &gt; Find Next</samp> to try to find the next
occurrence (there isn't one). You can search for any text that appears in
the rightmost columns (label, opcode, operand, comment).</p>
</div>
</div>
@ -203,8 +206,9 @@
<img src="images/t1-goto-box.png" alt="t1-goto-box"/>
</div>
<div class="grid-item-text">
<p>Select Navigate &gt; Go To. You can enter a label, address, or file offset.
Enter "100b" to set the selection to the line at address $100B.</p>
<p>Select <samp>Navigate &gt; Go To</samp>. You can enter a label,
address, or file offset. Enter "<kbd>100b</kbd>" to set the selection
to the line at address $100B.</p>
</div>
</div>
@ -220,6 +224,9 @@
on opcodes or lines in the side windows, the locations are added to a
navigation history. The arrows let you move forward and backward
through it.</p>
<p>The "Nav Backward" feature is bound to the 4th button found on some
mice (usually found on the side, activated with the thumb). This can
be used to navigate quickly through a project using only the mouse.</p>
</div>
</div>
@ -227,7 +234,7 @@
<div id="prevnext">
<a href="using-sourcegen.html" class="btn-previous">&laquo; Previous</a>
<a href="simple-edits.html" class="btn-next">Next &raquo;</a>
<a href="making-edits.html" class="btn-next">Next &raquo;</a>
</div>
<!-- START: /incl-footer.html -->

2
docs/sgtutorial/odds-ends.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>

2
docs/sgtutorial/prevnext.py
View File

@ -17,7 +17,7 @@ gFileList = [
"about-disasm.html",
"using-sourcegen.html",
"moving-around.html",
"simple-edits.html",
"making-edits.html",
"labels-symbols.html",
"editing-data.html",
"generating-code.html",

2
docs/sgtutorial/string-formatting.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>

51
docs/sgtutorial/suggestions.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
@ -94,40 +94,39 @@ suggestions to help you on your way.</p>
conventions, like whether to use MixedCase or underscore_separated
or SCREAMING_CAPS for labels.</li>
<li>Use the program thoroughly. Understand all of what it does.</li>
<li>Remember that SourceGen works by tracing through code from marked
start points, rather than treating everything as code and requiring you
to mark all the data items.
Begin each project by finding the code. Identify external
entry points, format tables of addresses, and find JSRs that are
followed by inline data. Use an extension script to handle the
inlines so you won't keep tripping over them. If parts of the program
are relocated to a different address, set the appropriate address
overrides.</li>
<ul>
<li>Code start tags are rarely needed, and code end tags are almost
never needed. You shouldn't have to spend a lot of time manually
tagging things. If a piece of code isn't being found, it's usually
best to figure out why the code that calls it isn't being found,
instead of trying to tag it and forge ahead from that point. It might
be dead code that's never called, or it might be called from a table
that you can format to add code entry tags for multiple addresses with
a single operation. Taking the time to find the table and format it
is faster than hand-formatting dozens of little handlers, and it's
something you'll need to do eventually anyway.</li>
</ul></li>
<li>Start with easily identifiable pieces. If a chunk of code is reading
from the keyboard, you can make reasonable guesses about the purpose of
the code that interacts with it.
<li>Start with easily identifiable subroutines. If a chunk of code is
reading from the keyboard, you can make reasonable guesses about the
purpose of the code that interacts with it.
The start of the program is often the hardest place to begin, because it
usually just initializes a bunch of stuff you haven't identified.</li>
<li>Expect to figure out little pieces. Use what you learn from these
to figure out other little pieces. It's a jigsaw puzzle, not a book.</li>
<li>Don't get discouraged if there's a ton of code that you can't make
sense of. It won't at first. Keep chipping away.</li>
sense of. It won't make sense at first. Keep chipping away.</li>
<li>Read <a href="https://6502disassembly.com/on-disassembly.html">On Disassembly</a>
for additional thoughts.</li>
</ul>
<p>Remember that SourceGen works by tracing through code from marked
start points, rather than treating everything as code and requiring you
to mark all the data items.
Begin each project by finding the code. Identify external
entry points, format tables of addresses, and find JSRs that are
followed by inline data. Use an extension script to handle the
inlines so you won't keep tripping over them. If parts of the program
are relocated to a different address, set the appropriate address
overrides.</p>
<p>Code start tags are rarely needed, and code end tags are almost
never needed. You shouldn't have to spend a lot of time manually
tagging things. If a piece of code isn't being found, it's usually
best to figure out why the code that calls it isn't being found,
instead of trying to tag it and forge ahead from that point. It might
be dead code that's never called, or it might be called from a table
that you can format to add code entry tags for multiple addresses with
a single operation. Taking the time to find the table and format it
is faster than hand-formatting dozens of little handlers, and it's
something you'll need to do eventually anyway.</p>
</div> <!-- #main -->
<div id="prevnext">

2
docs/sgtutorial/using-sourcegen.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen" class="active"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>

2
docs/sgtutorial/visualizations.html
View File

@ -58,7 +58,7 @@
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>