Add new symbol attributes (function_owner, allow_reference, `allo…

…w_be_referenced`) (#401)

* function_owner

* allow_reference and allow_be_referenced

* changelog and docs

* mypyblack

* spimdisasm

* rename

CHANGELOG.md

@@ -1,5 +1,13 @@
 # splat Release Notes
 
+### 0.27.1
+
+* Add new symbol attributes:
+  * `function_owner`: Allows to force a rodata symbol to be migrated to the given function, skipping over the rodata migration heuristic.
+  * `can_reference`: Allows toggling if the symbol is allowed to reference other symbols.
+  * `can_be_referenced`: Allows toggling if the symbol is allowed to be referenced by other symbols.
+* `spimdisasm` 1.29.0 or above is now required.
+
 ### 0.27.0
 
 * BREAKING: Renamed `auto_all_sections` to `auto_link_sections` and documented its behavior.

README.md

@@ -21,7 +21,7 @@ The brackets corresponds to the optional dependencies to install while installin
 If you use a `requirements.txt` file in your repository, then you can add this library with the following line:
 
 ```txt
-splat64[mips]>=0.27.0,<1.0.0
+splat64[mips]>=0.27.1,<1.0.0
 ```
 
 ### Optional dependencies

docs/Adding-Symbols.md

@@ -124,6 +124,21 @@ jtbl_800B13D0 = 0x800B13D0; // type:jtbl force_migration:True
 STR_800B32A8 = 0x800C9520; // type:asciz force_not_migration:True
 ```
 
+### `function_owner`
+
+Tells the disassembler that the given rodata symbol must be moved to the given function during rodata migration.
+
+This allows to override the rodata migration heuristic, which may decide to not migrate this symbol to a function or to migrate it to a different function.
+
+Make sure that the corresponding sections for the rodata symbol and the owner function are properly paired in the yaml, otherwise this symbol will be lost to limbo.
+
+This attribute is ignored if the `migrate_rodata_to_functions` option is disabled.
+
+**Example:**
+```ini
+D_800E86B0 = 0x800E86B0; // type:jtbl function_owner:func_8009F034
+```
+
 ### `allow_addend` and `dont_allow_addend`
 
 Allows this symbol to reference (or not reference) other symbols with an addend.
@@ -135,6 +150,34 @@ This attribute overrides the global `allow_data_addends` option.
 aspMainTextStart = 0x80084760; // dont_allow_addend:True
 ```
 
+### `can_reference`
+
+Allows this symbol to reference (or to not reference) other symbols.
+
+This can be desirable for textures, microcode, or any other symbol that should be treated as plain data.
+
+Defaults to `True`.
+
+**Example:**
+
+```ini
+aspMainTextStart = 0x80084760; // can_reference:False
+```
+
+### `can_be_referenced`
+
+Allows this symbol to be referenced (or to not be referenced) by other symbols.
+
+This can be desirable for some niche cases like games that include certain metadata that shouldn't be referenced by anything else, like relocation information in Zelda and Rare games.
+
+Defaults to `True`.
+
+**Example:**
+
+```ini
+dummy_symbol = 0x800782B0; // can_be_referenced:True
+```
+
 ### `allow_duplicated`
 
 Tells splat that a symbol is allowed to have its vram/name duplicated with another symbol.

docs/Configuration.md

@@ -112,7 +112,15 @@ generated_s_preamble: .set fp=64
 
 ### o_as_suffix
 
-Determines whether to replace the suffix of the file to `.o` or to append `.o` to the suffix of the file.
+Used to determine the file extension of the built files that will be listed on the linker script.
+
+Setting it to `True` tells splat to use `.o` as the file extension of the built file, replacing the existing one.
+For example `some_file.o`.
+
+Setting this to `False` appends `.o` to the extension of the file.
+For example `some_file.c.o`.
+
+Defaults to `False`.
 
 
 ### gp_value

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "splat64"
 # Should be synced with src/splat/__init__.py
-version = "0.27.0"
+version = "0.27.1"
 description = "A binary splitting tool to assist with decompilation and modding projects"
 readme = "README.md"
 license = {file = "LICENSE"}
@@ -20,7 +20,7 @@ dependencies = [
 
 [project.optional-dependencies]
 mips = [
-    "spimdisasm>=1.28.1,<2.0.0", # This value should be keep in sync with the version listed on disassembler/spimdisasm_disassembler.py
+    "spimdisasm>=1.29.0,<2.0.0", # This value should be keep in sync with the version listed on disassembler/spimdisasm_disassembler.py
     "rabbitizer>=1.12.0,<2.0.0",
     "pygfxd",
     "n64img>=0.3.3",

requirements.txt

@@ -4,7 +4,7 @@ tqdm
 intervaltree
 colorama
 # This value should be keep in sync with the version listed on disassembler/spimdisasm_disassembler.py and pyproject.toml
-spimdisasm>=1.28.1
+spimdisasm>=1.29.0
 rabbitizer>=1.10.0
 pygfxd
 n64img>=0.1.4

src/splat/__init__.py

@@ -1,7 +1,7 @@
 __package_name__ = __name__
 
 # Should be synced with pyproject.toml
-__version__ = "0.27.0"
+__version__ = "0.27.1"
 __author__ = "ethteck"
 
 from . import util as util

src/splat/disassembler/spimdisasm_disassembler.py

@@ -7,7 +7,7 @@
 
 class SpimdisasmDisassembler(disassembler.Disassembler):
     # This value should be kept in sync with the version listed on requirements.txt and pyproject.toml
-    SPIMDISASM_MIN = (1, 28, 1)
+    SPIMDISASM_MIN = (1, 29, 0)
 
     def configure(self):
         # Configure spimdisasm

src/splat/util/symbols.py

@@ -189,6 +189,9 @@ def get_seg_for_rom(rom: int) -> Optional["Segment"]:
                             if attr_name == "visibility":
                                 sym.given_visibility = attr_val
                                 continue
+                            if attr_name == "function_owner":
+                                sym.function_owner = attr_val
+                                continue
                         except:
                             log.parsing_error_preamble(path, line_num, line)
                             log.write(
@@ -232,6 +235,12 @@ def get_seg_for_rom(rom: int) -> Optional["Segment"]:
                             if attr_name == "dont_allow_addend":
                                 sym.dont_allow_addend = tf_val
                                 continue
+                            if attr_name == "can_reference":
+                                sym.can_reference = tf_val
+                                continue
+                            if attr_name == "can_be_referenced":
+                                sym.can_be_referenced = tf_val
+                                continue
                             if attr_name == "allow_duplicated":
                                 sym.allow_duplicated = True
                                 continue
@@ -470,10 +479,15 @@ def add_symbol_to_spim_segment(
         context_sym.forceMigration = True
     if sym.force_not_migration:
         context_sym.forceNotMigration = True
+    context_sym.functionOwnerForMigration = sym.function_owner
     if sym.allow_addend:
         context_sym.allowedToReferenceAddends = True
     if sym.dont_allow_addend:
         context_sym.notAllowedToReferenceAddends = True
+    if sym.can_reference is not None:
+        context_sym.allowedToReferenceSymbols = sym.can_reference
+    if sym.can_be_referenced is not None:
+        context_sym.allowedToBeReferenced = sym.can_be_referenced
     context_sym.setNameGetCallbackIfUnset(lambda _: sym.name)
     if sym.given_name_end:
         context_sym.nameEnd = sym.given_name_end
@@ -521,6 +535,7 @@ def add_symbol_to_spim_section(
         context_sym.forceMigration = True
     if sym.force_not_migration:
         context_sym.forceNotMigration = True
+    context_sym.functionOwnerForMigration = sym.function_owner
     context_sym.setNameGetCallbackIfUnset(lambda _: sym.name)
     if sym.given_name_end:
         context_sym.nameEnd = sym.given_name_end
@@ -610,10 +625,14 @@ class Symbol:
 
     force_migration: bool = False
     force_not_migration: bool = False
+    function_owner: Optional[str] = None
 
     allow_addend: bool = False
     dont_allow_addend: bool = False
 
+    can_reference: Optional[bool] = None
+    can_be_referenced: Optional[bool] = None
+
     linker_section: Optional[str] = None
 
     allow_duplicated: bool = False