Some repetitive formatting tasks can be handled with automatic scripts. This is especially useful for inline data, which can confuse the code analyzer.
An earlier tutorial demonstrated how to manually mark bytes as inline data. We're going to do it a faster way. For this tutorial, start a new project with the Generic 6502 profile, and in the SourceGen Examples/Tutorial directory select "Tutorial4".
We'll need to load scripts from the project directory, so we have to save the project. File > Save, use the default name ("Tutorial4.dis65").
Take a look at the disassembly listing. The file starts with a
JSR followed by a string that begins with a small number.
This appears to be a string with a leading length byte. We want to load
a script that can handle that, so use
Edit > Project Properties, select the
Extension Scripts tab, and click
Add Scripts from Project. The file
browser opens in the project directory. Select the file
"InlineL1String.cs", click Open, then OK.
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
JSR to a
PrintInlineL1String. So let's give it one.
JSR opcode on line $1000
to jump to address $1036. The only thing there is an
It's supposed to be a routine that prints a string with a leading length
byte, but for the sake of keeping the example code short it's just a
place-holder. Use the curly toolbar arrow
(or Alt+LeftArrow) to jump back to $1000.
This time, double-click the
("L1036") to edit the operand.
Click Create Label, and enter PrintInlineL1String.
Remember that labels are case-sensitive;
you must enter it exactly as shown. Hit OK to accept the label,
and OK to close the operand editor.
If all went well, address $1003
should now be an L1 string "
How long?", and address $100D
should be another
JSR appears to be followed by a null-terminated string, so
we'll need something that handles that.
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
JSR to a label
that starts with
PrintInlineNullString. So let's give it a couple of
Double-click the operand on line $100D ("
click Create Label,
and set the label to "PrintInlineNullStringOne".
Hit OK twice. That formatted the first one and got us
to the next
JSR. Repeat the process on line $1019
L1038"), setting the label to "PrintInlineNullStringTwo".
Things are looking good, but we've got one left, and it's got a
twist. Instead of a string, the
JSR 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.
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 OK twice. Note that the strings formatted earlier remain formatted.
Double-click the operand on line $1025 ("
click Create Label,
and set the label to "PrintInlineAddrString".
Hit OK twice. This formatted the address at $1028,
and also formatted the string at $102b as a null-terminated string.
Because the bytes were formatted as an address and not a just a
16-bit value, a label was generated automatically.
The entire project is now nicely formatted. In a real project the
"Print Inline" locations would be actual print functions, not just
instructions. There would likely be multiple
JSRs to the print function,
so labeling a single function entry point could format dozens of inline
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.
Extension scripts can make your life much easier, but they do require some programming experience. See the SourceGen manual for more details.