From cdefb150e309c2eeb5b5ab59689008dd2bfe8a07 Mon Sep 17 00:00:00 2001 From: AnonymousRandomPerson Date: Wed, 27 Dec 2023 15:48:42 -0600 Subject: [PATCH] Added more documentation to scripts --- tools/extract_function/extract_function.py | 13 +++++++++++-- tools/sync_pmdsky_debug/pmdsky_debug_reader.py | 3 +++ tools/sync_pmdsky_debug/symbol_details.py | 2 ++ tools/sync_pmdsky_debug/sync_from_pmdsky_debug.py | 6 ++++++ tools/sync_pmdsky_debug/sync_to_pmdsky_debug.py | 5 +++++ 5 files changed, 27 insertions(+), 2 deletions(-) diff --git a/tools/extract_function/extract_function.py b/tools/extract_function/extract_function.py index 20cd6fc6..8a82ebbe 100644 --- a/tools/extract_function/extract_function.py +++ b/tools/extract_function/extract_function.py @@ -19,6 +19,7 @@ if function_location.endswith('.s'): if function_header.endswith(';'): function_header = function_header[:-1] +# Extract the function name from the function header argument. left_parentheses_index = function_header.find('(') if left_parentheses_index >= 0: function_name = function_header[function_header.rfind(' ', None, left_parentheses_index) + 1 : left_parentheses_index] @@ -56,6 +57,7 @@ first_function_start_line = None def get_line_address(line: str): return line[line.index(ADDRESS_FIND) + len(ADDRESS_FIND) : -1] +# Find the start and end of the function within the ASM file. for i, line in enumerate(original_lines): if first_function_start_line is None and line.startswith(ARM_FUNC_START): first_function_start_line = i @@ -63,7 +65,7 @@ for i, line in enumerate(original_lines): function_start_line = i elif line.strip() == f'arm_func_end {function_name}'.strip(): function_end_line = i - + if function_start_line is not None and extract_function_address is None and ADDRESS_FIND in line: extract_function_address = get_line_address(line) if function_end_line is not None and ADDRESS_FIND in line: @@ -93,6 +95,7 @@ with open(LSF_FILE_PATH, 'r') as lsf_file: extract_file_name = f'{file_prefix}{extract_function_address}' +# If needed, add the extracted function's new .o file to main.lsf. merge_prev_file = None merge_next_file = None SRC_LSF_PREFIX = '\tObject src/' @@ -112,12 +115,15 @@ for i, line in enumerate(lsf_lines): if include_new_asm_file: lsf_lines[i] += f'\tObject asm/{file_prefix}{new_file_address}.o\n' break - + BRANCH_LINK_INSTRUCTION = '\tbl ' BRANCH_LINK_EXCHANGE_INSTRUCTION = '\tblx ' BRANCH_INSTRUCTION = '\tb ' WORD_KEY = '.word ' WORD_PLUS_OFFSET = ' + 0x' +""" +Searches through an ASM file's contents for all external symbosl, then populates a .inc file with all the necessary .public definitions. +""" def write_inc_file(lines: List[str], file_path: str): defined_functions = set() used_functions = set() @@ -189,6 +195,9 @@ function_body = f"""{function_header} }}""" +# Add the extracted function to a .h and .c file. +# If there is an existing C file adjacent to the extracted function, add the function to that file. +# Otherwise, make a new set of files. if merge_prev_file: header_file_path = os.path.join(HEADER_FOLDER, f'{merge_prev_file}.h') with open(header_file_path, 'r') as header_file: diff --git a/tools/sync_pmdsky_debug/pmdsky_debug_reader.py b/tools/sync_pmdsky_debug/pmdsky_debug_reader.py index 9ab5f50a..d54ddbd5 100644 --- a/tools/sync_pmdsky_debug/pmdsky_debug_reader.py +++ b/tools/sync_pmdsky_debug/pmdsky_debug_reader.py @@ -21,6 +21,9 @@ SYMBOL_BLACKLIST = set([ 'GAME_STATE_VALUES', ]) +""" +Returns the file path where pmdsky-debug is located locally, defined within pmdsky_debug_location.txt. +""" def get_pmdsky_debug_location() -> str: global pmdsky_debug_path if not pmdsky_debug_path: diff --git a/tools/sync_pmdsky_debug/symbol_details.py b/tools/sync_pmdsky_debug/symbol_details.py index 8bb96a61..b520acd0 100644 --- a/tools/sync_pmdsky_debug/symbol_details.py +++ b/tools/sync_pmdsky_debug/symbol_details.py @@ -1,5 +1,7 @@ from dataclasses import dataclass +# Some symbol names in the decomp do not match pmdsky-debug because of naming convention differences. +# Map these symbol names between the two projects to avoid changes when syncing the projects. MIXED_CASE_SYMBOLS_ARM9 = { '_secure': 'SECURE', '_start_AutoloadDoneCallback': 'StartAutoloadDoneCallback', diff --git a/tools/sync_pmdsky_debug/sync_from_pmdsky_debug.py b/tools/sync_pmdsky_debug/sync_from_pmdsky_debug.py index bbb11566..199b0a5e 100644 --- a/tools/sync_pmdsky_debug/sync_from_pmdsky_debug.py +++ b/tools/sync_pmdsky_debug/sync_from_pmdsky_debug.py @@ -16,6 +16,9 @@ pmdsky_debug_symbols = read_pmdsky_debug_symbols() xmap_symbols = read_xmap_symbols() asm_files = [] +""" +Searches for all files within a directory that have certain extensions. +""" def add_files_with_extensions(folder: str, extensions: List[str]) -> List[str]: found_files = [] for root, _, files in os.walk(folder): @@ -57,6 +60,8 @@ for language, pmdsky_debug_language_symbols in pmdsky_debug_symbols.items(): print(f'Replacing {old_symbol.name} with {symbol.name}') replaced_symbols.add(old_symbol.name) + + # Replace symbol occurrences in ASM files. if symbol.is_data: asm_search_string_bases = [ f'\n{old_symbol.name}:\n', @@ -100,6 +105,7 @@ for language, pmdsky_debug_language_symbols in pmdsky_debug_symbols.items(): with open(file_path, 'w') as asm_file: asm_file.write(asm_contents) + # Replace symbol occurrences in C files. src_search_string_data_regex = re.compile(fr'([ &*(]){old_symbol.name}([,); [])') src_search_string_data_regex_replace = fr'\1{symbol.name}\2' diff --git a/tools/sync_pmdsky_debug/sync_to_pmdsky_debug.py b/tools/sync_pmdsky_debug/sync_to_pmdsky_debug.py index 35ab37e4..7944b6c7 100644 --- a/tools/sync_pmdsky_debug/sync_to_pmdsky_debug.py +++ b/tools/sync_pmdsky_debug/sync_to_pmdsky_debug.py @@ -146,6 +146,7 @@ def sync_xmap_symbol(address: int, symbol: SymbolDetails, language: str, yaml_ma symbol_entry_addresses: int | List[int] = symbol_entry_language_addresses[language_key] + # If needed, reorder language addresses within the YAML for consistency with existing pmdsky-debug entries. hex_address = HexCapsInt(address) reorder_languages = language_key == 'EU' and len(symbol_entry_language_addresses) > 1 and not symbol_entry_language_addresses[language_key] if multiple_symbol_suffix.search(symbol.name): @@ -170,11 +171,14 @@ def sync_xmap_symbol(address: int, symbol: SymbolDetails, language: str, yaml_ma if symbol_preexisting: return + # Add the symbol to the correspond header file. base_symbol_path = base_symbol_path.replace('.yml', '.h') header_path = symbol_path.replace(SYMBOLS_FOLDER, os.path.join('headers', symbol_type_key)).replace('.yml', '.h') with open(header_path, 'r') as header_file: header_contents = header_file.readlines() + # Look for the symbol that was immediately before the new symbol in the YAML. + # The new symbol will be added directly after this anchor symbol. target_line = None if symbol_before is not None: for i, line in enumerate(header_contents): @@ -230,6 +234,7 @@ def sync_xmap_symbol(address: int, symbol: SymbolDetails, language: str, yaml_ma if f' {base_symbol_name}(' in line: symbol_header = line break + # Match the typedefs used in pmdsky-debug. symbol_header = symbol_header.replace('u32', 'uint32_t') symbol_header = symbol_header.replace('u16', 'uint16_t') symbol_header = symbol_header.replace('u8', 'uint8_t')