mirror of
https://github.com/fadden/6502bench.git
synced 2024-05-31 22:41:37 +00:00
Move symbol file and extension script docs into manual
Once upon a time, symbol files and extension scripts could only be defined in the RuntimeData directory, so having the documentation there made sense. Since both of these things can now be defined in project directories, the documentation belongs in the manual. (issue #27)
This commit is contained in:
Andy McFadden
parent
b37d3dba02
commit
2c03216da9
|
|
@ -10,6 +10,9 @@ You can download the source code and build it yourself, or click the
|
|||
[Releases tab](https://github.com/fadden/6502bench/releases) for
|
||||
pre-built downloads.
|
||||
|
||||
**Wanted:** ROM/OS symbols for various systems, notably Commodore and Atari
|
||||
home computers.
|
||||
|
||||
|
||||
## SourceGen ##
|
||||
|
||||
|
|
|
|||
|
|
@ -1,80 +0,0 @@
|
|||
# Extension Script Reference #
|
||||
|
||||
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.
|
||||
|
||||
## Features ##
|
||||
|
||||
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. Bear in mind that this
|
||||
feature is still evolving, and the interfaces may change significantly
|
||||
in the near future.
|
||||
|
||||
The current interfaces can be used to identify inline data that follows
|
||||
JSR/JSL instructions, and to format operands. The latter can be useful for
|
||||
replacing immediate load operands with symbolic constants.
|
||||
|
||||
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.
|
||||
|
||||
## Development ##
|
||||
|
||||
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.)
|
||||
|
||||
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.
|
||||
|
||||
## Utility Functions ##
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## PluginDll Directory ##
|
||||
|
||||
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.
|
||||
|
||||
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".
|
||||
|
||||
The PluginCommon and CommonUtil DLLs will be copied into the directory, so
|
||||
that code in the sandbox has access to them.
|
||||
|
||||
## Sandboxing ##
|
||||
|
||||
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.
|
||||
|
||||
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.)
|
||||
|
||||
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 *could* implement full security if
|
||||
circumstances change, so I'm using app domains as a way to keep everybody
|
||||
honest.
|
||||
|
|
@ -13,7 +13,160 @@
|
|||
<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 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 *could* implement full security if
|
||||
circumstances change, so I'm using app domains as a way to keep everybody
|
||||
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
|
||||
|
|
|
|||
|
|
@ -45,7 +45,8 @@ you edit an auto-generated label you will be required to change the name.</p>
|
|||
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.</p>
|
||||
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>
|
||||
|
|
|
|||
|
|
@ -113,6 +113,8 @@ and 65816 code. The official web site is
|
|||
|
||||
<li><a href="advanced.html">Advanced Topics</a></li>
|
||||
<ul>
|
||||
<li><a href="advanced.html#platform-symbols">Platform Symbol Files (.sym65)</a></li>
|
||||
<li><a href="advanced.html#extension-scripts">Extension Scripts</a></li>
|
||||
<li><a href="advanced.html#multi-bin">Working With Multiple Binaries</a></li>
|
||||
<li><a href="advanced.html#overlap">Overlapping Address Spaces</a></li>
|
||||
<li><a href="advanced.html#debug">Debug Menu Options</a></li>
|
||||
|
|
|
|||
|
|
@ -20,7 +20,9 @@ This opens the Create New Project window.</p>
|
|||
<p>Start by selecting your target system from the tree on the left.
|
||||
The panel on the right will show the CPU that will be selected, as well
|
||||
as the symbol files and extension scripts that will be loaded by default.
|
||||
All of these may be overridden later from the project properties.</p>
|
||||
All of these may be overridden later from the project properties.
|
||||
(If the description in the panel on the right says "[placeholder]", it
|
||||
means that the system doesn't yet have a set of symbols defined for it.)</p>
|
||||
|
||||
<p>Next, click the "Select File..." button. Pick the file you wish to
|
||||
disassemble. The dialog will update with the pathname and some notes
|
||||
|
|
|
|||
|
|
@ -207,9 +207,9 @@ to manually delete any symbols that are no longer being exported.</p>
|
|||
<p>From here, you can add and remove platform symbol files, or change
|
||||
the order in which they are loaded.
|
||||
See the <a href="intro.html#about-symbols">symbols</a> section for an
|
||||
explanation of how platform symbols work.
|
||||
See "README.md" in the RuntimeData directory for a description of the
|
||||
file syntax.</p>
|
||||
explanation of how platform symbols work, and the
|
||||
<a href="advanced.html#platform-symbols">advanced topics</a> section
|
||||
for a description of the file syntax.</p>
|
||||
|
||||
<p>Platform symbol files must live in the RuntimeData directory that comes
|
||||
with SourceGen, or in the directory where the project file lives. This
|
||||
|
|
|
|||
|
|
@ -50,47 +50,13 @@ All "RT:" identifier paths are relative to the RuntimeData directory. The
|
|||
Group Name is not automatically added.
|
||||
|
||||
|
||||
## Platform Symbol Files (.sym65) ##
|
||||
## Platform Symbol Files and Extension Scripts ##
|
||||
|
||||
These contain lists of symbols, each of which has a label and a value.
|
||||
If two symbols have the same value, the older one is discarded.
|
||||
|
||||
Blank lines, and lines that begin with a semicolon (';'), are ignored.
|
||||
|
||||
Lines that begin with an asterisk are command lines. Two commands are
|
||||
currently defined:
|
||||
|
||||
- *SYNOPSIS - a short summary of the file contents.
|
||||
- *TAG - a tag string to apply to all following symbols.
|
||||
|
||||
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 tag is cleared.
|
||||
|
||||
All other lines are expected to have the form:
|
||||
|
||||
symbol {=|@} value [;comment]
|
||||
|
||||
Symbols 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. Different assemblers have different
|
||||
limitations on symbols, but all reasonable assemblers will accept these.
|
||||
|
||||
Use '@' for address values, and '=' for constants. The only real difference
|
||||
is that address values will be applied automatically to operands that
|
||||
reference addresses outside the scope of the file.
|
||||
|
||||
The value is a number in decimal, hexadecimal (with a leading '$'), or
|
||||
binary (with a leading '%'). The numeric base will be saved and used when
|
||||
formatting the symbol in the generated output, so use whichever form is
|
||||
most appropriate. Values are unsigned 24-bit numbers.
|
||||
|
||||
The comment is optional. If present, it will be saved and used as the
|
||||
end-of-line comment on the equate directive if the symbol is used.
|
||||
These are described in the "Advanced Topics" section of the manual
|
||||
([here](Help/advanced.html)).
|
||||
|
||||
|
||||
## Extension Scripts ##
|
||||
## Misc Files ##
|
||||
|
||||
See "ExtensionScripts.md".
|
||||
LegalStuff.txt, Logo.png, and AboutImage.png are displayed by SourceGen,
|
||||
on the start screen and the About box.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user