align attribute for symbols

CHANGELOG.md

@@ -1,5 +1,11 @@
 # splat Release Notes
 
+### 0.36.0
+
+* Add new symbol attribute: `align`.
+  * Emit an alignment directive for the given symbol during disassembly.
+  * The given alignment must be positive, be a power of two and The symbol's address must already be aligned to the given custom alignment, otherwise splat will emit an error and halt.
+
 ### 0.35.2
 
 * Miscellaneous updates to generated macro labels.

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.35.2,<1.0.0
+splat64[mips]>=0.36.0,<1.0.0
 ```
 
 ### Optional dependencies

docs/Adding-Symbols.md

@@ -209,3 +209,27 @@ __opPCc__Q23std34_RefCountedPtr<c,Q23std9_Array<c>>CFv = 0x00202850; // filename
 ```
 
 Gets written to `func_00202850.s`
+
+### `align`
+
+Emit an alignment directive for the given symbol during disassembly.
+
+Even when an explicit alignment directive is not necessary in most situations, it may be desired to have one on shiftable builds on partially matched projects, allowing to ensure the symbol's required alignment even when it is still being disassembled. Some situations that may require an explicit alignment directive include textures in N64 (0x8 alignment) or symbols sent to the IOP on PS2 (0x40 alignment).
+
+The symbol's address must already be aligned to the given custom alignment, otherwise the alignment will be discarded.
+
+This value must be a power of two, otherwise it will be discarded.
+
+**Example**
+
+```ini
+rgb_texture = 0x82013118; // align:0x8
+```
+
+Produces a disassembly similar to the following:
+
+```mips
+.align 3
+dlabel rgb_texture
+# ...
+```

docs/Configuration.md

@@ -579,7 +579,7 @@ Defaults to `True`, meaning `bss` sections will be put on `NOLOAD` segments.
 
 Specify that segments should be aligned before starting them.
 
-This option specifies the desired alignment value, or `null` if no aligment should be imposed on the segment start.
+This option specifies the desired alignment value, or `null` if no alignment should be imposed on the segment start.
 
 This behavior can be customized per segment too. See [ld_align_segment_start](Segments.md#ld_align_segment_start) on the Segments section.
 

docs/Segments.md

@@ -542,7 +542,7 @@ Defaults to the value of the global option.
 
 Specify the current segment should be aligned before starting it.
 
-This option specifies the desired alignment value, or `null` if no aligment should be imposed on the segment start.
+This option specifies the desired alignment value, or `null` if no alignment should be imposed on the segment start.
 
 If not set, then the global configuration is used. See [ld_align_segment_start](Configuration.md#ld_align_segment_start) on the Configuration section.
 

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "splat64"
 # Should be synced with src/splat/__init__.py
-version = "0.35.2"
+version = "0.36.0"
 description = "A binary splitting tool to assist with decompilation and modding projects"
 readme = "README.md"
 license = {file = "LICENSE"}

src/splat/__init__.py

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

src/splat/util/symbols.py

@@ -192,6 +192,28 @@ def get_seg_for_rom(rom: int) -> Optional["Segment"]:
                             if attr_name == "function_owner":
                                 sym.function_owner = attr_val
                                 continue
+                            if attr_name == "align":
+                                align = int(attr_val, 0)
+
+                                if align < 0:
+                                    log.parsing_error_preamble(path, line_num, line)
+                                    log.error(
+                                        f"The given alignment for '{sym.name}' (0x{sym.vram_start:08X}) is negative."
+                                    )
+                                align_shift = (align & (-align)).bit_length() - 1
+                                if (1 << align_shift) != align:
+                                    log.parsing_error_preamble(path, line_num, line)
+                                    log.error(
+                                        f"The given alignment '0x{align:X}' for symbol '{sym.name}' (0x{sym.vram_start:08X}) is not a power of two."
+                                    )
+                                if sym.vram_start % align != 0:
+                                    log.parsing_error_preamble(path, line_num, line)
+                                    log.error(
+                                        f"The symbol '{sym.name}' (0x{sym.vram_start:08X}) is not aligned already to the given alignment '0x{align:X}'."
+                                    )
+
+                                sym.given_align = align
+                                continue
                         except:
                             log.parsing_error_preamble(path, line_num, line)
                             log.write(
@@ -520,6 +542,8 @@ def add_symbol_to_spim_segment(
         context_sym.nameEnd = sym.given_name_end
     if sym.given_visibility:
         context_sym.visibility = sym.given_visibility
+    if sym.given_align:
+        context_sym.setAlignment(sym.given_align)
 
     return context_sym
 
@@ -568,6 +592,8 @@ def add_symbol_to_spim_section(
         context_sym.nameEnd = sym.given_name_end
     if sym.given_visibility:
         context_sym.visibility = sym.given_visibility
+    if sym.given_align:
+        context_sym.setAlignment(sym.given_align)
 
     return context_sym
 
@@ -667,6 +693,8 @@ class Symbol:
     given_filename: Optional[str] = None
     given_visibility: Optional[str] = None
 
+    given_align: Optional[int] = None
+
     _generated_default_name: Optional[str] = None
     _last_type: Optional[str] = None