Configuration - ethteck/splat GitHub Wiki
Splat has various options for configuration, all of which are listed under the options
section of the yaml file.
Project configuration
base_path
Path that all other configured paths are relative to.
Usage
base_path: path/to/base/folder
Default
.
(Current directory)
target_path
Path to target binary.
Usage
target_path: path/to/target/binary
elf_path
Path to the final elf target
Default
Path to the binary that was used as the input to python3 -m splat create_config
platform
The target platform for the binary. Options are:
n64
(Nintendo 64)psx
(PlayStation 1)ps2
(PlayStation 2)psp
(PlayStation Portable)
Usage
platform: psx
compiler
Compiler used to build the binary.
splat recognizes the following compilers, and it will adapt it behavior accordingly for them, but unknown compilers can be passed as well:
- GCC
- SN64
- IDO
Usage
compiler: IDO
Default
ido
endianness
Determines the endianness of the target binary. If not set, the endiannesss will be guessed from the selected platform.
Valid values:
- big
- little
section_order
Determines the default section order of the target binary. This can be overridden per-segment.
Expects a list of strings.
generated_c_preamble
String that is placed before the contents of newly-generated .c
files.
Usage
generated_c_preamble: #include "header.h"
Default
#include "common.h"
generated_s_preamble
String that is placed before the contents of newly-generated assembly (.s
) files.
Usage
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.
gp_value
The value of the $gp
register to correctly calculate offset to %gp_rel
relocs.
check_consecutive_segment_types
By default splat will check and error if there are any non consecutive segment types. This option disables said feature.
Usage
# Disable checking for non-consecutive segments
check_consecutive_segment_types: False
Paths
asset_path
Path to output split asset files.
Usage
asset_path: path/to/assets/folder
Default
assets
symbol_addrs_path
Determines the path to the symbol addresses file(s). A symbol_addrs
file is to be updated/curated manually and contains addresses of symbols as well as optional metadata such as rom address, type, and more
It's possible to use more than one file by supplying a list instead of a string
Usage
symbol_addrs_path: path/to/symbol_addrs
Default
symbol_addrs.txt
reloc_addrs_paths
build_path
Path that built files will be found. Used for generation of the linker script.
Usage
build_path: path/to/build/folder
Default
build
src_path
Path to split .c
files.
Usage
src_path: path/to/src/folder
Default
src
asm_path
Path to output split assembly files.
Usage
asm_path: path/to/asm/folder
Default
asm
data_path
Determines the path to the asm data directory
nonmatchings_path
Determines the path to the asm nonmatchings directory
matchings_path
Determines the path to the asm matchings directory (used alongside disassemble_all
to organize matching functions from nonmatching functions)
cache_path
Path to splat cache
Usage
cache_path: path/to/splat/cache
Default
.splat_cache
hasm_in_src_path
Tells splat to consider hasm
files to be relative to src_path
instead of asm_path
.
Usage
hasm_in_src_path: True
Default
False
create_undefined_funcs_auto
If True
, splat will generate an undefined_funcs_auto.txt
file.
Usage
create_undefined_funcs_auto: False
Default
True
undefined_funcs_auto_path
Path to file containing automatically defined functions.
Usage
undefined_funcs_auto_path: path/to/undefined_funcs_auto.txt
Default
undefined_funcs_auto.txt
create_undefined_syms_auto
If True
, splat will generate an undefined_syms_auto.txt
file.
Usage
create_undefined_syms_auto: False
Default
True
undefined_syms_auto_path
Path to file containing automatically defined symbols.
Usage
undefined_syms_auto_path: path/to/undefined_syms_auto.txt
Default
undefined_syms_auto.txt
extensions_path
If you are using splat extension(s), this is the path they will be loaded from.
Usage
extensions_path: path/to/extensions/folder
Default
tools/splat_ext
lib_path
Determines the path to library files that are to be linked into the target binary when the lib
segment type is used.
elf_section_list_path
Path to file containing elf section list.
Usage
elf_section_list_path: path/to/elf_sections
Default
elf_sections.txt
Linker script
subalign
Sub-alignment (in bytes) of sections.
subalign
can be null
to not force any specific alignment and use the built section's declared alignment instead.
Usage
subalign: 4
Default
16
auto_link_sections
A list of linker sections for which entries will be automatically added to the linker script. If a segment contains 10 "c" subsegments, one can rely on this feature to automatically create linker entries for these files in the specified sections. This feature reduces the need to manually add lines to your yaml which only would serve to add linker entries for common sections, such as .data, .rodata, and .bss.
Default
[".data", ".rodata", ".bss"]
ld_script_path
Path to output ld script.
Usage
ld_script_path: path/to/ld/script.ld
Default
{basename}.ld
ld_symbol_header_path
Path to output a header containing linker symbols.
Usage
ld_symbol_header_path: path/to/linker_symbol_header
ld_discard_section
Determines whether to add a discard section to the linker script
ld_wildcard_sections
Determines whether to add wildcards for section linking in the linker script (.rodata* for example)
ld_use_symbolic_vram_addreses
Determines whether to use follows_vram
(segment option) and vram_symbol
/ follows_classes
(vram_class options) to calculate vram addresses in the linker script.
Enabled by default. If disabled, this uses the plain integer values for vram addresses defined in the yaml.
ld_partial_linking
Change linker script generation to allow partially linking segments. Requires both ld_partial_scripts_path
and ld_partial_build_segments_path
to be set.
ld_partial_scripts_path
Folder were each intermediary linker script will be written to.
ld_partial_build_segments_path
Folder where the built partially linked segments will be placed by the build system.
ld_dependencies
Generate a dependency file for every linker script generated. Dependency files will have the same path and name as the corresponding linker script, but changing the extension to .d
. Requires elf_path
to be set.
ld_legacy_generation
Currently splat imposes the given section_order
when generating the linker script. But in some cases it may not be desirable to impose the section ordering because the ROM itself may not follow a logical section ordering.
To disable this behavior then turn on the ld_legacy_generation
option. This way splat will blindly follow the yaml order, allowing to interleave unrelated sections. This setting must be treated as a last resort, since most ROMs do follow a logical ordering. If some specific files have weird ordering on one of their sections then it is recommended to use the linker_section_order
attribute of a given file entry instead.
This option defaults to False
.
segment_end_before_align
If enabled, the end symbol for each segment will be placed before the alignment directive for the segment
segment_symbols_style
Controls the style of the auto-generated segment symbols in the linker script.
Possible values:
- splat
- makerom
ld_rom_start
Specifies the starting offset for rom address symbols in the linker script.
ld_fill_value
Allows to specify the value of the FILL
statement generated on every segment of the linker script.
It must be either an integer, which will be used as the parameter for the FILL
statement, or null
, which tells splat to not emit FILL
statements.
This behavior can be customized per segment too. See ld_fill_value on the Segments section.
Defaults to 0.
ld_bss_is_noload
Allows to control if bss
sections (and derivatived sections) will be put on a NOLOAD
segment on the generated linker script or not.
Applies to all bss
(sbss
, common
, scommon
, etc) sections.
Defaults to True
, meaning bss
sections will be put on NOLOAD
segments.
ld_align_segment_start
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 behavior can be customized per segment too. See ld_align_segment_start on the Segments section.
Defaults to null
.
ld_align_segment_vram_end
Allows to toggle aligning the *_VRAM_END
linker symbol of each segment.
Setting this to True
will make the *_VRAM_END
to be aligned to the configured alignment of the segment.
Defaults to True
.
ld_align_section_vram_end
Allows to toggle aligning the *_VRAM_END
linker symbol of each section for every segment.
Setting this to True
will make the *_END
linker symbol of every section to be aligned to the configured alignment of the segment.
Defaults to True
.
ld_generate_symbol_per_data_segment
If enabled, the generated linker script will have a linker symbol for each data file.
Defaults to True
.
ld_bss_contains_common
Sets the default option for the bss_contains_common
attribute of all segments.
Defaults to False
.
C file options
create_c_files
Determines whether to create new c files if they don't exist
auto_decompile_empty_functions
Determines whether to "auto-decompile" empty functions
do_c_func_detection
Determines whether to detect matched/unmatched functions in existing c files so we can avoid creating .s
files for already-decompiled functions.
c_newline
Determines the newline char(s) to be used in c files
(Dis)assembly-related options
symbol_name_format
Determine the format that symbols should be named by default
symbol_name_format_no_rom
Same as symbol_name_format
but for symbols with no rom address
find_file_boundaries
Determines whether to detect and hint to the user about likely file splits when disassembling.
This setting can also be set on a per segment basis, if you'd like to enable or disable detection for specific segments. This could be useful when you are confident you identified all subsegments in a segment, yet splat
still hints that subsegments could be split.
pair_rodata_to_text
Determines whether to detect and hint to the user about possible rodata sections corresponding to a text section
migrate_rodata_to_functions
Determines whether to attempt to automatically migrate rodata into functions
asm_inc_header
Determines the header to be used in every asm file that's included from c files
asm_function_macro
Determines the macro used to declare functions in asm files
asm_function_alt_macro
Determines the macro used to declare symbols in the middle of functions in asm files (which may be alternative entries)
asm_jtbl_label_macro
Determines the macro used to declare jumptable labels in asm files
asm_data_macro
Determines the macro used to declare data symbols in asm files
asm_end_label
Determines the macro used at the end of a function, such as endlabel or .end
asm_ehtable_label_macro
Determines the macro used to declare ehtable labels in asm files.
Defaults to ehlabel
asm_emit_size_directive
Toggles the .size directive emitted by the disassembler
mnemonic_ljust
Determines the number of characters to left align before the instruction
rom_address_padding
Determines whether to pad the rom address
mips_abi_gpr
Determines which ABI names to use for general purpose registers
mips_abi_float_regs
Determines which ABI names to use for floating point registers.
Valid values:
- numeric
- o32
- n32
- n64
`o32`` is highly recommended, as it provides logically named registers for floating point instructions. For more info, see https://gist.github.com/EllipticEllipsis/27eef11205c7a59d8ea85632bc49224d
named_regs_for_c_funcs
Determines whether functions inside c files should have named registers
add_set_gp_64
Determines whether to add ".set gp=64" to asm/hasm files
create_asm_dependencies
Generate .asmproc.d
dependency files for each C file which still reference functions in assembly files
string_encoding
Global option for rodata string encoding. This can be overriden per segment
data_string_encoding
Global option for data string encoding. This can be overriden per segment
rodata_string_guesser_level
Global option for the rodata string guesser. 0 disables the guesser completely.
data_string_guesser_level
Global option for the data string guesser. 0 disables the guesser completely.
allow_data_addends
Global option for allowing data symbols using addends on symbol references. It can be overriden per symbol
disasm_unknown
Tells the disassembler to try disassembling functions with unknown instructions instead of falling back to disassembling as raw data
detect_redundant_function_end
Tries to detect redundant and unreferenced functions ends and merge them together. This option is ignored if the compiler is not set to IDO.
disassemble_all
Don't skip disassembling already matched functions and migrated sections
global_vram_start and global_vram_end
Allow specifying that the global memory range may be larger than what was automatically detected.
Useful for projects where splat is used in multiple individual files, meaning the expected global segment may not be properly detected because each instance of splat can't see the info from other files, like in PSX and PSP projects.
use_gp_rel_macro_nonmatching
If True then use the %gp_rel
explicit relocation parameter on instructions that use the $gp register, otherwise strip the %gp_rel
parameter entirely
and convert those instructions into macro instructions that may not assemble to the original bytes.
In the latter case, it is the user's responsability to provide the symbol's information to the assembler so it can assemble the instruction with the
proper relocation, for example by declaring the required symbol on the corresponding .c
or .cpp
file.
Turning off this setting may be useful for projects with old assemblers that do not support %gp_rel
, like PS2 and PSP projects.
This setting is applied exclusively to c
segments (functions under the nonmatchings folder).
Defaults to True
use_gp_rel_macro
Does the same as use_gp_rel_macro_nonmatching
, except it is only applied to asm
and hasm
segments.
Defaults to True
N64-specific options
header_encoding
Used to specify what encoding should be used used when parsing the N64 ROM header.
Default
ASCII
gfx_ucode
Determines the type gfx ucode (used by gfx segments)
Valid options are:
- f3d
- f3db
- f3dex
- f3dexb
- f3dex2
libultra_symbols
Use named libultra symbols by default. Those will need to be added to a linker script manually by the user
ique_symbols
Use named libultra symbols by default. Those will need to be added to a linker script manually by the user
hardware_regs
Use named hardware register symbols by default. Those will need to be added to a linker script manually by the user
image_type_in_extension
Append the type of an image to its file extension. For example, when enabled, a ci4 named texture
would export with filename texture.ci4.png
.
Compiler-specific options
use_legacy_include_asm
If True
, generate c files using the longer old INCLUDE_ASM
macro. The non-legacy INCLUDE_ASM
macro is highly recommended, and the legacy version is only supported for compatibility reasons.
For more information on these macros, see macros.
Usage
use_legacy_include_asm: True
Default
False