ConvSym 2.12: Support symbol references in -ref and -org options.

* Added support for symbol references instead of raw offsets in `-ref` and `-org` options: - Specify `-ref @MySymbol` to substitute offset of `MySymbol` from the symbol table (before any transformations or filtering); - This is useful, for example, if you need to write symbol table pointer in ROM, but you don't know pointer's offset beforehand - you can now reference it by symbol name. * Minor stability improvements and general optimizations; * Document more usage examples in the README.
vladikcomper · Dec 10, 2024 · bac9715 · bac9715
1 parent e713df2
commit bac9715
Show file tree

Hide file tree

Showing 14 changed files with 48 additions and 27 deletions.
diff --git a/utils/convsym/README.md b/utils/convsym/README.md
@@ -99,13 +99,19 @@ Offsets conversion options:
 
 Symbol table dump options:
   -org [offset]
+  -org @[symbolName]
     If set, symbol data will placed at the specified [offset] in the output 
     file. This option cannot be used in "append mode".
+    You can specify @SomeSymbol instead of plain offset, in this case ConvSym 
+    will resolve that symbol's offset.
 
   -ref [offset]
+  -ref @[symbolName]
     If set, a 32-bit Big Endian offset pointing to the beginning of symbol
     data will be written at specified offset. This is can be used, 
     if symbol data pointer must be written somewhere in the ROM header.
+    You can specify @SomeSymbol instead of plain offset, in this case ConvSym 
+    will resolve that symbol's offset.
 
 Symbols conversion and filtering options:
   -toupper
@@ -129,33 +135,40 @@ Symbols conversion and filtering options:
 
 ### Examples
 
-Convert listing file `listing.lst` in `as_lst` format to `symbols.log` of `log` format:
+**Default options.** Converts ASM68K symbol file to DEB2 format (implies `-input asm68k_sym` and `-output deb2` for default parsers respectively):
+
+```sh
+convsym symbols.sym symbols.deb2
+```
+
+**Append to ROM.** Converts ASM68K symbol file to DEB2 format (`-output deb2`) and appends it (`-a`) to the end of ROM (for use with MD Debugger):
+
+```sh
+convsym symbols.sym rom.bin -output deb2 -a
+```
+
+**AS Listing to Log file.** Convert listing file `listing.lst` in `as_lst` format to `symbols.log` of `log` format:
 
 ```sh
 convsym listing.lst symbols.log -input as_lst -output log
 ```
 
-Convert listing file `listing.lst` in `as_lst` format to `deb2` format and append to the end of `rom.bin` file:
+**Symbol filtering and transformation.** Converts from plaintext symbol table (log file), excludes symbols starting with "z80" (`-filter "z80.+" -exclude`), converts everything to lowercase for better compression (`-tolower`) and appends to ROM and writes a 32-bit Big-Endian pointer to the symbol table (where it was appended) at offset 0x200 of ROM (`-ref 200`):
 
 ```sh
-convsym listing.lst rom.bin -input as_lst -output deb2 -a
+convsym symbols.log rom.bin -input log -a -filter "z80.+" -exclude -tolower -ref 200
 ```
 
 ## Converting SGDK symbols
 
-> [!WARNING]
-> 
-> SGDK isn't officially supported by the "Advanced Error Handler and Debugger", which makes use of the converted symbols, hence no installation instructions are provided.
-> At this point, you'll have to figure out installation on your own.
-
 Since **version 2.11** ConvSym supports converting symbols in SGDK projects.
 
 SGDK logs all symbols to `symbol.txt` file upon build. Since version 2.11 ConvSym introduced `txt` input parser which can be configured to recognize this file's format.
 
 Here's how ConvSym can be invoked in the command line to store symbols from `out/symbol.txt` file in `out/rom.bin`:
 
 ```sh
-convsym out/symbol.txt out/rom.bin -in txt -inopt "/fmt='%X %*[tTtBbCcDd] %511s /offsetFirst+" -range 0 FFFFFF -a -ref 200
+convsym out/symbol.txt out/rom.bin -in txt -inopt "/fmt='%X %*[tTtBbCcDd] %511s /offsetFirst+" -range 0 FFFFFF -a -ref @MDDBG__SymbolTablePtr
 ```
 
 Let's break down command line options:
@@ -169,7 +182,7 @@ Let's break down command line options:
    - For more information, search reference for `sscanf` format (C standard library), which is used under the hood here.
 - `-range 0 FFFFFF` - adds both ROM and RAM symbols to the output (covers the entire 68K 24-bit address space), it would've been only ROM by default (`-range 0 3FFFFF`);
 - `-a` - appends output file (the ROM) instead of overwriting it;
-- `-ref 200` - writes reference pointer to the symbol table (where ROM was appended) at offset 0x200 so MD Debugger can read it (**WARNING!** Make sure you've allocated 4 bytes for the pointer at that offset, after the ROM header).
+- `-ref @MDDBG__SymbolTablePtr` - writes reference pointer to the symbol table (where ROM was appended) at offset specified by the `MDDBG__SymbolTablePtr` symbol in ROM so MD Debugger can read it (**WARNING!** Make sure this symbol exists, or ConvSym will fail).
 
 
 ## Input formats parsers
@@ -459,6 +472,15 @@ Before **version 2.11** format string option could be specified as follows (this
 
 ## Version history
 
+### Version 2.12 (2024-12-11)
+
+* Added support for symbol references instead of raw offsets in `-ref` and `-org` options:
+  - Specify `-ref @MySymbol` to substitute offset of `MySymbol` from the symbol table (before any transformations or filtering);
+  - This is useful, for example, if you need to write symbol table pointer in ROM, but you don't know pointer's offset beforehand - you can now reference it by symbol name.
+
+* Minor stability improvements and general optimizations;
+* Document more usage examples in the README.
+
 ### Version 2.11 (2024-12-08)
 
 * Added new `txt` input parser to parse arbitrary text files; ConvSym can now parse SGDK's `symbols.txt` file.
@@ -490,7 +512,6 @@ Before **version 2.11** format string option could be specified as follows (this
 * `asm` and `log` output parsers:
   - Properly report I/O error if output file couldn't be opened.
 
-
 ### Version 2.9.1 (2023-03-22)
 
 * `asm68k_sym` parser:

diff --git a/utils/convsym/src/input/ASM68K_Listing.cpp b/utils/convsym/src/input/ASM68K_Listing.cpp
@@ -1,6 +1,6 @@
 
 /* ------------------------------------------------------------ *
- * ConvSym utility version 2.11									*
+ * ConvSym utility version 2.12									*
  * Input wrapper for the ASM68K listing format					*
  * ------------------------------------------------------------	*/
 

diff --git a/utils/convsym/src/input/ASM68K_Sym.cpp b/utils/convsym/src/input/ASM68K_Sym.cpp
@@ -1,6 +1,6 @@
 
 /* ------------------------------------------------------------ *
- * ConvSym utility version 2.11									*
+ * ConvSym utility version 2.12									*
  * Input wrapper for the ASM68K compiler's symbol format		*
  * ------------------------------------------------------------	*/
 

diff --git a/utils/convsym/src/input/AS_Listing.cpp b/utils/convsym/src/input/AS_Listing.cpp
@@ -1,6 +1,6 @@
 
 /* ------------------------------------------------------------ *
- * ConvSym utility version 2.11									*
+ * ConvSym utility version 2.12									*
  * Input wrapper for the AS listing format						*
  * ------------------------------------------------------------	*/
 

diff --git a/utils/convsym/src/input/AS_Listing_Experimental.cpp b/utils/convsym/src/input/AS_Listing_Experimental.cpp
@@ -1,6 +1,6 @@
 
 /* ------------------------------------------------------------ *
- * ConvSym utility version 2.11									*
+ * ConvSym utility version 2.12									*
  * Input wrapper for the AS listing format						*
  * ------------------------------------------------------------	*/
 

diff --git a/utils/convsym/src/input/Log.cpp b/utils/convsym/src/input/Log.cpp
@@ -1,6 +1,6 @@
 
 /* ------------------------------------------------------------ *
- * ConvSym utility version 2.11									*
+ * ConvSym utility version 2.12									*
  * Input wrapper for log files									*
  * ------------------------------------------------------------	*/
 

diff --git a/utils/convsym/src/input/TXT.cpp b/utils/convsym/src/input/TXT.cpp
@@ -1,6 +1,6 @@
 
 /* ------------------------------------------------------------ *
- * ConvSym utility version 2.11									*
+ * ConvSym utility version 2.12									*
  * Input wrapper for TXT files									*
  * ------------------------------------------------------------	*/
 

diff --git a/utils/convsym/src/input/Wrappers.cpp b/utils/convsym/src/input/Wrappers.cpp
@@ -1,6 +1,6 @@
 
 /* ------------------------------------------------------------ *
- * ConvSym utility version 2.11									*
+ * ConvSym utility version 2.12									*
  * Input formats base controller								*
  * ------------------------------------------------------------	*/
 

diff --git a/utils/convsym/src/main.cpp b/utils/convsym/src/main.cpp
@@ -1,6 +1,6 @@
 
 /* ------------------------------------------------------------ *
- * ConvSym utility version 2.11									*
+ * ConvSym utility version 2.12									*
  * Main definitions file										*
  * (c) 2017-2018, 2020-2024, Vladikcomper						*
  * ------------------------------------------------------------	*/
@@ -21,8 +21,8 @@
 #include <tuple>
 #include <variant>
 
-#include "input/Wrappers.cpp"	// for GetInputWrapper[..]() and their linkage
-#include "output/Wrappers.cpp"	// for GetOutputWrapper[..]() and their linkage
+#include "input/Wrappers.cpp"	// for getInputWrapper[..]() and their linkage
+#include "output/Wrappers.cpp"	// for getOutputWrapper[..]() and their linkage
 #include "util/SymbolTable.hpp"
 
 
@@ -32,7 +32,7 @@ int main (int argc, const char ** argv) {
 	/* Provide help if no sufficient arguments were passed */
 	if (argc<2) {
 		printf(
-			"ConvSym utility version 2.11\n"
+			"ConvSym utility version 2.12\n"
 			"(c) 2016-2024, vladikcomper\n"
 			"\n"
 			"Command line arguments:\n"

diff --git a/utils/convsym/src/output/ASM.cpp b/utils/convsym/src/output/ASM.cpp
@@ -1,6 +1,6 @@
 
 /* ------------------------------------------------------------ *
- * ConvSym utility version 2.11									*
+ * ConvSym utility version 2.12									*
  * Output wrapper for assembly file with equates				*
  * ------------------------------------------------------------	*/
 

diff --git a/utils/convsym/src/output/DEB1.cpp b/utils/convsym/src/output/DEB1.cpp
@@ -1,6 +1,6 @@
 
 /* ------------------------------------------------------------ *
- * ConvSym utility version 2.11									*
+ * ConvSym utility version 2.12									*
  * Output wrapper for the Debug Information format version 1.0	*
  * ------------------------------------------------------------	*/
 

diff --git a/utils/convsym/src/output/DEB2.cpp b/utils/convsym/src/output/DEB2.cpp
@@ -1,6 +1,6 @@
 
 /* ------------------------------------------------------------ *
- * ConvSym utility version 2.11									*
+ * ConvSym utility version 2.12									*
  * Output wrapper for the Debug Information format version 2.0	*
  * ------------------------------------------------------------	*/
 

diff --git a/utils/convsym/src/output/Log.cpp b/utils/convsym/src/output/Log.cpp
@@ -1,6 +1,6 @@
 
 /* ------------------------------------------------------------ *
- * ConvSym utility version 2.11									*
+ * ConvSym utility version 2.12									*
  * Output wrapper for simple symbol logging						*
  * ------------------------------------------------------------	*/
 

diff --git a/utils/convsym/src/output/Wrappers.cpp b/utils/convsym/src/output/Wrappers.cpp
@@ -1,6 +1,6 @@
 
 /* ------------------------------------------------------------ *
- * ConvSym utility version 2.11									*
+ * ConvSym utility version 2.12									*
  * Output formats base controller								*
  * ------------------------------------------------------------	*/