mirror of
https://github.com/fadden/6502bench.git
synced 2024-12-11 13:50:13 +00:00
268 lines
12 KiB
HTML
268 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>Advanced Topics - 6502bench SourceGen</title>
|
|
</head>
|
|
|
|
<body>
|
|
<div id="content">
|
|
<h1>6502bench SourceGen: Advanced Topics</h1>
|
|
<p><a href="index.html">Back to index</a></p>
|
|
|
|
|
|
<h2><a name="platform-symbols">Platform Symbol Files (.sym65)</a></h2>
|
|
|
|
<p>Platform symbol files contain lists of symbols, each of which has a
|
|
label and a value. SourceGen comes with a collection of symbols for
|
|
popular systems, but you can create your own. This can be handy if a
|
|
few different projects are coded against a common library.</p>
|
|
|
|
<p>If two symbols have the same value, the older symbol is replaced by
|
|
the newer one. This is why the order in which symbols file are loaded
|
|
matters.</p>
|
|
|
|
<p>Platform symbol files consist of comments, commands, and symbols.
|
|
Blank lines, and lines that begin with a semicolon (';'), are ignored. Lines
|
|
that begin with an asterisk ('*') are commands. Two are currently
|
|
defined:</p>
|
|
<ul>
|
|
<li>*SYNOPSIS - a short summary of the file contents.</li>
|
|
<li>*TAG - a tag string to apply to all symbols that follow in this
|
|
file.</li>
|
|
</ul>
|
|
|
|
<p>Tags can be used by extension scripts to identify a subset of symbols.
|
|
The symbols are still part of the global set; the tag just provides a
|
|
way to extract a subset. Tags should be comprised of non-whitespace ASCII
|
|
characters. Tags are global, so use a long, descriptive string. If *TAG
|
|
is not followed by a string, the symbols that follow are treated as
|
|
untagged.</p>
|
|
|
|
<p>All other lines are symbols, which have the form:</p>
|
|
<pre>
|
|
label {=|@} value [;comment]
|
|
</pre>
|
|
|
|
<p>Labels must be at least two characters long, begin with a letter or
|
|
underscore, and consist entirely of alphanumeric ASCII characters
|
|
(A-Z, a-z, 0-9) and the underscore ('_'). (This is the same format
|
|
required for line labels in SourceGen.)</p>
|
|
<p>Use '@' for address values, and '=' for constants. The only important
|
|
difference between them is that address values will be applied automatically
|
|
to operands that reference addresses outside the scope of the file.
|
|
Constants are never applied automatically.</p>
|
|
|
|
<p>The value is a number in decimal, hexadecimal (with a leading '$'), or
|
|
binary (with a leading '%'). The numeric base will be recorded and used when
|
|
formatting the symbol in generated output, so use whichever form is most
|
|
appropriate. Values are unsigned 24-bit numbers.</p>
|
|
|
|
<p>The comment is optional. If present, it will be saved and used as the
|
|
end-of-line comment on the .EQ directive if the symbol is used.</p>
|
|
|
|
<h3>Creating a Project-Specific Symbol File</h3>
|
|
|
|
<p>To create a platform symbol file for your project, just create a new
|
|
text file, named with a ".sym65" extension. (If your text editor of choice
|
|
doesn't like that, you can put a ".txt" on the end while you're editing.)
|
|
Make sure you create it in the same directory where your project file
|
|
(the file that ends with ".dis65") lives. Add a *SYNOPSIS, then add
|
|
the desired symbols.</p>
|
|
<p>Finally, add it to your project. Select Edit > Project Properties,
|
|
switch to the Symbol Files tab, click Add Symbol Files, and select your
|
|
symbol file. It should appear in the list with a "PROJ:" prefix.</p>
|
|
|
|
<p>If an example helps, the A2-Amper-fdraw project in the Examples
|
|
directory has a project-local symbol file, called "fdraw-exports".
|
|
(Amper-fdraw provides an Applesoft BASIC interface to a machine-language
|
|
library.)</p>
|
|
|
|
<p>NOTE: in the current version of SourceGen, changes to .sym65 files are
|
|
not detected automatically. Closing and re-opening the project
|
|
(File > Close, then click on the first recent-file link) will reload
|
|
them.</p>
|
|
|
|
|
|
<h2><a name="extension-scripts">Extension Scripts</a></h2>
|
|
|
|
<p>Extension scripts, also called "plugins", are C# programs with access to
|
|
the full .NET Standard 2.0 APIs. They're compiled at run time by SourceGen
|
|
and executed in a sandbox with security restrictions.</p>
|
|
|
|
<p>SourceGen defines an interface that plugins must implement, and an
|
|
interface that plugins can use to interact with SourceGen. See
|
|
Interfaces.cs in the PluginCommon directory. <b>Bear in mind that this
|
|
feature is still evolving, and the interfaces may change significantly
|
|
in the near future.</b></p>
|
|
|
|
<p>The current interfaces can be used to identify inline data that follows
|
|
JSR, JSL, or BRK instructions, and to format operands. The latter can be
|
|
useful for replacing immediate load operands with symbolic constants.</p>
|
|
|
|
<p>Scripts may be loaded from the RuntimeData directory, or from the directory
|
|
where the project file lives. Attempts to load them from other locations
|
|
will fail.</p>
|
|
|
|
<h4>Development</h4>
|
|
|
|
<p>The easiest way to develop extension scripts is inside the 6502bench
|
|
solution in Visual Studio. This way you have the interfaces available
|
|
for IntelliSense completion, and get all the usual syntax and compile
|
|
checking in the editor. (This is why there's a RuntimeData project for
|
|
Visual Studio.)</p>
|
|
|
|
<p>If you have the solution configured for debug builds, SourceGen will set
|
|
the IncludeDebugInformation flag to true when compiling scripts. This
|
|
causes a .PDB file to be created.</p>
|
|
|
|
<p>Some commonly useful functions are defined in the PluginCommon.Util class,
|
|
which is available to plugins. These call into the CommonUtil library,
|
|
which is shared with SourceGen.</p>
|
|
|
|
<p>While plugins can use CommonUtil directly, they should avoid doing so. The
|
|
APIs there are not guaranteed to be stable, so plugins that rely on them
|
|
may break in a subsequent release of SourceGen.</p>
|
|
|
|
<h4>PluginDll Directory</h4>
|
|
|
|
<p>Extension scripts are compiled into .DLLs, and saved in the PluginDll
|
|
directory, which lives next to the application executable and RuntimeData.
|
|
If the extension script is the same age or older than the DLL, SourceGen
|
|
will continue to use the existing DLL.</p>
|
|
|
|
<p>The DLLs names are a combination of the script filename and script location.
|
|
The compiled name for "MyPlatform/MyScript.cs" in the RuntimeData directory
|
|
will be "RT_MyPlatform_MyScript.dll". For a project-specific script, it
|
|
would look like "PROJ_MyProject_MyScript.dll".</p>
|
|
|
|
<p>The PluginCommon and CommonUtil DLLs will be copied into the directory, so
|
|
that code in the sandbox has access to them.</p>
|
|
|
|
<h4>Sandboxing</h4>
|
|
|
|
<p>Extension scripts are executed in an App Domain sandbox. App domains are
|
|
a .NET feature that creates a partition inside the virtual machine, isolating
|
|
code. It still runs in the same address space, on the same threads, so the
|
|
isolation is only effective for "partially trusted" code that has been
|
|
declared safe by the bytecode verifier.</p>
|
|
|
|
<p>SourceGen disallows most actions, notably file access. An exception is
|
|
made for reading files from the directory where the plugin DLLs live, but
|
|
scripts are otherwise unable to read or write from the filesystem. (A
|
|
future version of SourceGen may provide an API that allows limited access
|
|
to data files.)</p>
|
|
|
|
<p>App domain security is not absolute. I don't really expect SourceGen to
|
|
be used as a malware vector, so there's no value in forcing scripts to
|
|
execute in an isolated server process, or to jump through the other hoops
|
|
required to really lock things down. I do believe there's value in
|
|
defining the API in such a way that we <b>could</b> implement full security if
|
|
circumstances change, so I'm using app domains as a way to keep the API
|
|
honest.</p>
|
|
|
|
|
|
<h2><a name="multi-bin">Working With Multiple Binaries</a></h2>
|
|
|
|
<p>Sometimes a program is split into multiple files on disk. They
|
|
may be all loaded at once, or some may be loaded into the same place
|
|
at different times. In such situations it's not uncommon for one
|
|
file to provide a set of interfaces that other files use. It's
|
|
useful to have symbols for these interfaces be available to all
|
|
projects.</p>
|
|
<p>There are two ways to do this: (1) define a common platform symbol
|
|
file with the relevant addresses, and keep it up to date as you work;
|
|
or (2) declare the labels as global and exported, and import them
|
|
as project symbols into the other projects.</p>
|
|
<p>Support for this is currently somewhat weak, requiring a manual
|
|
symbol-import step in every interested project. This step must be
|
|
repeated whenever the labels are updated.</p>
|
|
<p>A different but related problem is typified by arcade ROM sets,
|
|
where files are split apart because each file must be burned into a
|
|
separate PROM. All files are expected to be present in memory at
|
|
once, so there's no reason to treat them as separate projects. Currently,
|
|
the best way to deal with this is to concatenate the files into a single
|
|
file, and operate on that.</p>
|
|
|
|
<h2><a name="overlap">Overlapping Address Spaces</a></h2>
|
|
<p>Some programs use memory overlays, where multiple parts of the
|
|
code run in the same address in RAM. Others use bank switching to access
|
|
parts of the program that reside in separate physical RAM, but appear at
|
|
the same address.</p>
|
|
<p>SourceGen allows you to set the same address on multiple parts of
|
|
a file. Branches to a given address are resolved against the current
|
|
segment first. For example, consider this:</p>
|
|
<pre>
|
|
.ORG $1000
|
|
JMP L1100
|
|
|
|
.ORG $1100
|
|
L1100 BIT L1100
|
|
L1103 LDA #$11
|
|
BRA L1103
|
|
|
|
.ORG $1100
|
|
L1100_0 BIT L1100_0
|
|
L1103_0 LDA #$22
|
|
JMP L1103_0
|
|
</pre>
|
|
|
|
<p>Both sections start at $1100, and have branches to $1103. The branch
|
|
in the first section resolves to the label in the first version of
|
|
that address chunk, while the branch in the second section resolves to
|
|
the label in the second chunk. When branches originate outside the current
|
|
address chunk, the first chunk that includes that address is used, as
|
|
it is with the <code>JMP $1000</code> at the start of the file.</p>
|
|
|
|
|
|
<h2><a name="debug">Debug Menu Options</a></h2>
|
|
|
|
<p>The DEBUG menu is hidden by default in release builds, but can be
|
|
exposed by checking the "enable DEBUG menu" box in the application
|
|
settings. These features are used for debugging SourceGen. They will
|
|
not help you debug 6502 projects.</p>
|
|
|
|
<p>Features:</p>
|
|
<ul>
|
|
<li>Re-analyze (F5). Causes a full re-analysis. Useful if you think
|
|
the display is out of sync.</li>
|
|
<li>Show Undo/Redo History. Opens a floating window that lets you
|
|
watch the contents of the undo buffer while you work.</li>
|
|
<li>Show Analyzer Output. Opens a floating window with a text log from
|
|
the most recent analysis pass. The exact contents will vary depending
|
|
on how the verbosity level is configured internally. Debug messages
|
|
from extension scripts appear here.</li>
|
|
<li>Show Analysis Timers. Opens a floating window with a dump of
|
|
timer results from the most recent analysis pass. Times for individual
|
|
stages are noted, as are times for groups of functions. This
|
|
provides a crude sense of where time is being spent.</li>
|
|
<li>Extension Script Info. Shows a bit about the currently-loaded
|
|
extension scripts.</li>
|
|
<li>Toggle Comment Rulers. Adds a string of digits above every
|
|
multi-line comment (long comment, note). Useful for confirming that
|
|
the width limitation is being obeyed. These are added exactly
|
|
as shown, without comment delimiters, into generated assembly output,
|
|
which doesn't work out well if you run the assembler.</li>
|
|
<li>Use Keep-Alive Hack. If set, a "ping" is sent to the extension
|
|
script sandbox every 60 seconds. This seems to be required to avoid
|
|
an infrequently-encountered Windows bug. (See code for notes and
|
|
stackoverflow.com links.)</li>
|
|
<li>Source Generation Tests. Opens the regression test harness. See
|
|
the README.md in the SGTestData directory for more information. If
|
|
the regression tests weren't included in the SourceGen distribution,
|
|
this will have nothing to do.</li>
|
|
</ul>
|
|
|
|
|
|
</div>
|
|
|
|
<div id="footer">
|
|
<p><a href="index.html">Back to index</a></p>
|
|
</div>
|
|
</body>
|
|
<!-- Copyright 2018 faddenSoft -->
|
|
</html>
|