align attribute for symbols (#480)

* Allow setting custom alignment to a symbol

* black

* Update docs/Adding-Symbols.md

* Update docs/Adding-Symbols.md

Author: AngheloAlf

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ### 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.
 * New yaml option: `include_asm_macro_style`:
   * Allows configuring the style used by the generated `INCLUDE_ASM` macro. It currently allows two possible values:
   * `default`: Uses the default definition for the macro. This is the default.

docs/Adding-Symbols.md

@@ -209,3 +209,29 @@ __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 though an explicit alignment directive is not necessary in most situations, it may be desirable to have one on shiftable builds of partially matched projects. This allows ensuring 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, or the value 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

@@ -588,7 +588,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.
 

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