### VramOffset Usage Examples Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/addresses/struct.VramOffset.html Demonstrates basic instantiation and arithmetic operations using VramOffset and Vram. ```rust use rabbitizer::vram::{VramOffset, Vram}; let offset = VramOffset::new(-0x10); let vram = Vram::new(0x80000100); assert_eq!(vram + offset, Vram::new(0x800000F0)); ``` ```rust use rabbitizer::vram::{VramOffset, Vram}; let offset = VramOffset::new(0x8); let vram = Vram::new(0x80000100); assert_eq!(offset.add_vram(&vram), Vram::new(0x80000108)); ``` ```rust use rabbitizer::vram::{VramOffset, Vram}; let offset = VramOffset::new(0); let vram = Vram::new(0x80000100); assert!(offset.is_zero()); assert_eq!(offset + vram, vram); ``` ```rust use rabbitizer::vram::{VramOffset, Vram}; let offset = VramOffset::new(0x20); let vram = Vram::new(0x80000100); assert!(offset.is_positive()); assert_eq!((offset + vram).inner(), 0x80000120); ``` ```rust use rabbitizer::vram::{VramOffset, Vram}; let offset = VramOffset::new(-0x20); let vram = Vram::new(0x80000100); assert!(offset.is_negative()); assert_eq!((offset + vram).inner(), 0x800000E0); ``` -------------------------------- ### Initialization and Configuration Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/symbols/display/function_display.rs.html Provides details on how to initialize the disassembler and configure its display settings. ```APIDOC ## POST /initialize ### Description Initializes a new instance of the disassembler with specified display flags. ### Method POST ### Endpoint /initialize ### Parameters #### Request Body - **display_flags** (InstructionDisplayFlags) - Required - Flags to control instruction display. ### Request Example ```json { "display_flags": "some_flags" } ``` ### Response #### Success Response (200) - **Self** (object) - The newly created disassembler instance. #### Response Example ```json { "instance_id": "unique_instance_identifier" } ``` ## POST /set_rom_comment_width ### Description Sets the width for ROM comments in the disassembler output. ### Method POST ### Endpoint /set_rom_comment_width ### Parameters #### Path Parameters - **rom_comment_width** (u8) - Required - The desired width for ROM comments. ### Request Example ```json { "rom_comment_width": 10 } ``` ### Response #### Success Response (200) - **Status** (string) - Indicates the success of the operation. #### Response Example ```json { "status": "success" } ``` ``` -------------------------------- ### Get Start Bound of Range Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/addresses/struct.AddressRange.html Returns the start bound of the AddressRange as a RangeBounds trait method. ```rust fn start_bound(&self) -> Bound<&T> ``` -------------------------------- ### GpConfig Constructor Methods Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/config/gp_config.rs.html Methods to initialize a new GpConfig instance for either sdata or PIC configurations. ```APIDOC ## GpConfig::new_sdata ### Description Creates a new GpConfig instance configured for sdata. ### Parameters - **gp_value** (GpValue) - Required - The global pointer value. ### Request Example GpConfig::new_sdata(gp_value) ## GpConfig::new_pic ### Description Creates a new GpConfig instance configured for Position Independent Code (PIC). ### Parameters - **gp_value** (GpValue) - Required - The global pointer value. ### Request Example GpConfig::new_pic(gp_value) ``` -------------------------------- ### Get Start of AddressRange Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/addresses/struct.AddressRange.html Returns the start value of the AddressRange. Requires T to be Copy, PartialOrd, and Debug. ```rust pub const fn start(&self) -> T ``` -------------------------------- ### Initialize SymCommonDisplaySettings Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/symbols/display/sym_common_display.rs.html Creates a new instance of SymCommonDisplaySettings with default values. ```rust impl SymCommonDisplaySettings { #[must_use] pub fn new() -> Self { Self { line_end: None, emit_asm_comment: true, asm_indentation: 4, rom_comment_width: 6, } } #[must_use] pub fn line_end(&self) -> &str { if let Some(line_end) = &self.line_end { line_end } else { "\n" } } } impl SymCommonDisplaySettings { pub fn set_rom_comment_width(&mut self, rom_comment_width: u8) { self.rom_comment_width = rom_comment_width; } } ``` -------------------------------- ### Get ROM Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/symbol_metadata.rs.html Accessor method to get the ROM address of the symbol. ```rust pub fn rom(&self) -> Option { self.rom } ``` -------------------------------- ### Initialize GlobalOffsetTableIter Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/addresses/global_offset_table.rs.html Creates a new iterator for the GlobalOffsetTable, starting with a given VRAM address and a reference to the GlobalOffsetTable itself. ```rust pub struct GlobalOffsetTableIter<'got> { current_vram: Vram, got: &'got GlobalOffsetTable, } impl<'got> GlobalOffsetTableIter<'got> { #[must_use] pub fn new(got: &'got GlobalOffsetTable) -> Self { Self { current_vram: got.vram().start(), got, } } } ``` -------------------------------- ### Get Size Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/symbol_metadata.rs.html Accessor method to get the size of the symbol. Currently marked with TODO. ```rust pub fn size(&self) -> Option { // TODO } ``` -------------------------------- ### Get SymbolNameGenerationSettings Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/symbol_metadata.rs.html Accessor method to get a reference to the symbol name generation settings. ```rust pub fn symbol_name_generation_settings(&self) -> &SymbolNameGenerationSettings { &self.symbol_name_generation_settings } ``` -------------------------------- ### NobitsSectionSettings::new Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/sections/before_proc/struct.NobitsSectionSettings.html Creates a new instance of NobitsSectionSettings, optionally accepting a compiler configuration. ```APIDOC ## pub fn new(compiler: Option) -> Self ### Description Creates a new instance of NobitsSectionSettings. This is the primary constructor for the struct. ### Parameters #### Request Body - **compiler** (Option) - Optional - The compiler configuration to use for the section settings. ``` -------------------------------- ### Get User Declared Name Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/symbol_metadata.rs.html Accessor method to get a clone of the user-declared symbol name. ```rust pub(crate) fn user_declared_name(&self) -> Option> { self.user_declared_name.clone() } ``` -------------------------------- ### Configure and Register GOT for Testing Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/analysis/register_tracker.rs.html Sets up local and global GOT entries, constructs a GlobalOffsetTable, and registers it for testing with specific GP configuration. Ensure `BYTES`, `expected_gpr_values`, and `expected_operations` are defined elsewhere. ```rust let got_locals = vec![ /* -0x7FF0($gp) */ GotLocalEntry::new(0x0F000000), /* Lazy resolver */ /* -0x7FEC($gp) */ GotLocalEntry::new(0x80000000), /* GNU extension */ /* -0x7FE8($gp) */ GotLocalEntry::new(0x80000000), /* */ ]; let got_globals = vec![ /* -0x7FE4($gp) */ GotGlobalEntry::new(0x80000134, 0x80000134, false, "some_var"), /* some_var + 0x8 */ /* -0x7FE0($gp) */ GotGlobalEntry::new(0x800000C4, 0x800000C4, false, "global_function"), /* global_function */ /* -0x7FDC($gp) */ GotGlobalEntry::new(0x8000014C, 0x8000014C, false, "func_arr"), /* func_arr */ /* -0x7FD8($gp) */ GotGlobalEntry::new(0x8000012C, 0x8000012C, false, "some_var"), /* some_var */ ]; let got = GlobalOffsetTable::new(Vram::new(0x80000110), got_locals, got_globals); let gp_config = Some(GpConfig::new_pic(GpValue::new(0x80008100))); let global_offset_table = Some(&got); register_tracking_general_test( &BYTES, &expected_gpr_values, &expected_operations, gp_config, global_offset_table, ); ``` -------------------------------- ### GlobalConfigBuilder Initialization and Building Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/config/struct.GlobalConfigBuilder.html Provides methods for creating a new GlobalConfigBuilder and for building the final GlobalConfig object. ```APIDOC ## GlobalConfigBuilder ### Description Represents a builder for configuring global settings of the spimdisasm. ### Methods #### `new(endian: Endian) -> Self` Creates a new `GlobalConfigBuilder` with the specified endianness. #### `build(self) -> GlobalConfig` Consumes the builder and returns the constructed `GlobalConfig`. ``` -------------------------------- ### Get Mutable ROM Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/symbol_metadata.rs.html Mutable accessor method to get a mutable reference to the ROM address. ```rust pub(crate) fn rom_mut(&mut self) -> &mut Option { &mut self.rom } ``` -------------------------------- ### Get Mutable Autodetected Size Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/symbol_metadata.rs.html Mutable accessor method to get a mutable reference to the autodetected size. ```rust pub(crate) fn autodetected_size_mut(&mut self) -> &mut Option { &mut self.autodetected_size } ``` -------------------------------- ### Initialize ContextBuilder Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/context/builder/context_builder.rs.html Creates a new `ContextBuilder` with provided global and user segment heaters. Initializes empty overlays and overlay names. ```rust pub fn new(global_segment: GlobalSegmentHeater, user_segment: UserSegmentBuilder) -> Self { Self { global_segment, user_segment, overlays: Vec::new(), overlay_names: UnorderedSet::new(), } } ``` -------------------------------- ### Get TypeId of a Generic Type Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/addresses/struct.GotGlobalEntry.html Gets the TypeId of a generic type T. This is part of the Any trait implementation. ```rust fn type_id(&self) -> TypeId ``` -------------------------------- ### From and Into Implementations Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/addresses/struct.AddressRange.html Explains the blanket implementations of `From` for `T` and `Into` for `T` when `U` implements `From`. ```APIDOC ## impl From for T ### Description Blanket implementation of `From` for `T`. ### Methods #### fn from(t: T) -> T Returns the argument unchanged. ## impl Into for T ### Description Blanket implementation of `Into` for `T`. ### Constraints - `U: From` ### Methods #### fn into(self) -> U Calls `U::from(self)`. ``` -------------------------------- ### Detect Function Start and Advance NOPs Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/sections/before_proc/executable_section.rs.html Logic for identifying the start of a function while skipping NOP instructions. ```rust 828 if let Some((func_sym, user_size)) = 829 current_function_ref.and_then(|x| x.user_declared_size().map(|y| (x, y))) 830 { 831 // If the user told us about the size of this function then we should blindly trust it (as long as it is valid) 832 833 // This whole section assumes every symbol is a multiple of a word. We shouldn't let the user break that assumption. 834 if user_size.inner() % BYTES_PER_INSTR != 0 { 835 return Err(BadUserSymbolSizeError::new( 836 "".into(), 837 func_sym.vram(), 838 user_size, 839 SECTION_TYPE, 840 BYTES_PER_INSTR, 841 ) 842 .into()); 843 } 844 845 *index += (user_size.inner() / BYTES_PER_INSTR) as usize; 846 find_current_start( 847 owned_segment, 848 section_vram, 849 instrs, 850 index, 851 current_function_ref.as_ref(), 852 starts_data, 853 false, 854 ) 855 } else if owned_segment 856 .find_reference( 857 section_vram + Size::new((*index as u32 + 1) * BYTES_PER_INSTR), 858 FindSettings::new(false), 859 ) 860 .is_some() 861 { 862 // Check for 1 instruction functions 863 *index += 1; 864 find_current_start( 865 owned_segment, 866 section_vram, 867 instrs, 868 index, 869 current_function_ref.as_ref(), 870 starts_data, 871 false, 872 ) 873 } else { 874 Ok(NextStartResult::FunctionStart( 875 *index * BYTES_PER_INSTR as usize, 876 current_function_ref, 877 )) 878 } 879 } 880} 881 882fn find_current_start_advance_nops<'segment>( 883 owned_segment: &'segment SegmentMetadata, 884 section_vram: Vram, 885 instrs: &[Instruction], 886 index: &mut usize, 887) -> Option> { 888 let mut current_function_ref = None; 889 890 // Loop over until we find a instruction that isn't a nop or a referenced function 891 while *index < instrs.len() { 892 current_function_ref = owned_segment.find_reference( 893 section_vram + Size::new(*index as u32 * BYTES_PER_INSTR), 894 FindSettings::new(false), 895 ); 896 897 if current_function_ref.is_some() { 898 break; 899 } 900 901 let instr = &instrs[*index]; 902 if !instr.is_nop() { 903 break; 904 } 905 906 *index += 1; 907 } 908 909 current_function_ref 910} ``` -------------------------------- ### Configuration Methods Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/config/global_config.rs.html Methods for initializing and configuring the disassembly environment. ```APIDOC ## POST /build ### Description Builds the global configuration based on current settings. ### Method POST ### Endpoint /build ### Response #### Success Response (200) - **GlobalConfig** (object) - The resulting global configuration object. --- ## POST /set_gp_config ### Description Sets the global pointer (GP) configuration. ### Method POST ### Endpoint /set_gp_config ### Parameters #### Request Body - **gp_config** (GpConfig) - Required - The GP configuration object to apply. --- ## POST /set_macro_labels ### Description Sets the macro labels for the disassembly process. ### Method POST ### Endpoint /set_macro_labels ### Parameters #### Request Body - **macro_labels** (Option) - Optional - The macro labels to be used. --- ## POST /set_emit_size_directive ### Description Configures whether to emit size directives in the output. ### Method POST ### Endpoint /set_emit_size_directive ### Parameters #### Request Body - **emit_size_directive** (bool) - Required - Boolean flag to enable or disable size directives. ``` -------------------------------- ### Get Mutable User Declared Size Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/symbol_metadata.rs.html Mutable accessor method to get a mutable reference to the user-declared size. ```rust pub(crate) fn user_declared_size_mut(&mut self) -> &mut Option { &mut self.user_declared_size } ``` -------------------------------- ### Initialize Context with New Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/context/the_context.rs.html Creates a new `Context` instance with provided global configuration, segment metadata, overlay segments, and preheated sections. Initializes an unknown segment and an empty set for created no-load sections. ```rust impl Context { pub(crate) fn new( global_config: GlobalConfig, global_segment: SegmentMetadata, user_segment: UserSegmentMetadata, overlay_segments: UnorderedMap, preheated_sections: UnorderedMap, ) -> Self { Self { global_config, global_segment, user_segment, overlay_segments, unknown_segment: SegmentMetadata::new_unknown_segment(), preheated_sections, created_noload_sections: UnorderedSet::new(), } } } ``` -------------------------------- ### TryFrom and TryInto Implementations Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/addresses/struct.AddressRange.html Explains the blanket implementations of `TryFrom` for `T` (when `U: Into`) and `TryInto` for `T` (when `U: TryFrom`). ```APIDOC ## impl TryFrom for T ### Description Blanket implementation of `TryFrom` for `T`. ### Constraints - `U: Into` ### Associated Types #### type Error = Infallible ### Methods #### fn try_from(value: U) -> Result>::Error> Performs the conversion. ## impl TryInto for T ### Description Blanket implementation of `TryInto` for `T`. ### Constraints - `U: TryFrom` ### Associated Types #### type Error = >::Error ### Methods #### fn try_into(self) -> Result>::Error> Performs the conversion. ``` -------------------------------- ### Get Mutable SymbolNameGenerationSettings Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/symbol_metadata.rs.html Mutable accessor method to get a mutable reference to the symbol name generation settings. ```rust pub(crate) fn symbol_name_generation_settings_mut( &mut self, ) -> &mut SymbolNameGenerationSettings { &mut self.symbol_name_generation_settings } ``` -------------------------------- ### Define AddressRange Struct Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/addresses/address_range.rs.html Defines a generic AddressRange struct with start and end fields. Ensures start is less than or equal to end upon creation. ```rust 1/* SPDX-FileCopyrightText: © 2024-2025 Decompollaborate */ 2/* SPDX-License-Identifier: MIT */ 3 4use core::{fmt, ops}; 5 6use super::{Rom, Size, Vram}; 7 8#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)] 9pub struct AddressRange { 10 start: T, 11 end: T, 12} 13 14impl 15where 16 T: Copy + PartialOrd + fmt::Debug, 17{ 18 #[must_use] 19 pub fn new(start: T, end: T) -> Self { 20 assert!( 21 start <= end, 22 "An address range can't contain an `end` value that's smaller than the `start` one. start: {start:?}, end: {end:?}" 23 ); 24 Self { start, end } 25 } 26 27 #[must_use] 28 pub const fn start(&self) -> T { 29 self.start 30 } 31 32 #[must_use] 33 pub const fn end(&self) -> T { 34 self.end 35 } 36} ``` -------------------------------- ### ContextBuilder Methods Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/context/builder/struct.ContextBuilder.html Methods for initializing a new ContextBuilder, adding overlays, and finalizing the context build process. ```APIDOC ## ContextBuilder Methods ### new - **Description**: Creates a new instance of ContextBuilder. - **Parameters**: - **global_segment** (GlobalSegmentHeater) - Required - **user_segment** (UserSegmentBuilder) - Required ### add_overlay - **Description**: Adds an overlay segment to the builder. - **Parameters**: - **overlay** (OverlaySegmentHeater) - Required - **Returns**: Result<(), AddOverlayToBuilderError> ### build - **Description**: Finalizes the context construction. - **Parameters**: - **global_config** (GlobalConfig) - Required - **Returns**: Result ``` -------------------------------- ### FindSettings::new Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/collections/addended_ordered_map/struct.FindSettings.html Creates a new instance of FindSettings with the specified addend configuration. ```APIDOC ## pub const fn new(allow_addend: bool) -> Self ### Description Creates a new FindSettings instance. ### Parameters #### Request Body - **allow_addend** (bool) - Required - Determines whether addends are allowed in the search settings. ### Response #### Success Response (200) - **FindSettings** (struct) - A new instance of FindSettings. ``` -------------------------------- ### Get Encoding Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/sections/before_proc/struct.DataSectionSettings.html Retrieves the Encoding setting from DataSectionSettings. ```rust pub fn encoding(&self) -> Encoding ``` -------------------------------- ### Module before_proc Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/sections/before_proc/index.html Documentation for the 'before_proc' module within the spimdisasm crate. ```APIDOC ## Module before_proc ### Description This module contains procedures related to processing before main execution. ### Submodules - `spimdisasm::sections` ``` -------------------------------- ### Get GotGlobalEntry Address Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/addresses/struct.GotGlobalEntry.html Returns the address of the GotGlobalEntry. ```rust pub const fn address(&self) -> u32 ``` -------------------------------- ### SymbolMetadata Constructor Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/symbol_metadata.rs.html Demonstrates the creation of a new SymbolMetadata instance with required parameters. ```APIDOC ## SymbolMetadata::new ### Description Creates a new `SymbolMetadata` instance, initializing essential fields. ### Method `new( generated_by: GeneratedBy, vram: Vram, owner_segment_kind: OwnerSegmentKind, symbol_name_generation_settings: SymbolNameGenerationSettings, ) -> Self` ### Parameters - **generated_by** (GeneratedBy) - Information about how the symbol was generated. - **vram** (Vram) - The virtual RAM address of the symbol. - **owner_segment_kind** (OwnerSegmentKind) - The kind of segment that owns this symbol. - **symbol_name_generation_settings** (SymbolNameGenerationSettings) - Settings for generating the symbol's name. ### Returns A new `SymbolMetadata` instance. ``` -------------------------------- ### Get Length of UnorderedMap Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/collections/unordered_map.rs.html Returns the number of elements in the map. ```rust pub fn len(&self) -> usize { self.inner.len() } ``` -------------------------------- ### MIPS Assembly GP Pairing and GOT Usage Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/analysis/register_tracker.rs.html Demonstrates various MIPS assembly patterns for PIC (Position Independent Code) including GP initialization, GOT access, and function calls. ```asm .abicalls .set noreorder .set noat .section .text .globl silly_func .type silly_func, @function silly_func: .ent silly_func lui $gp, %hi(_gp_disp) addiu $gp, $gp, %lo(_gp_disp) addu $gp, $gp, $t9 addiu $sp, $sp, -0x20 sw $ra, 0x10($sp) sw $gp, 0x18($sp) lui $a0, %hi(some_var) addiu $a1, $a0, %lo(some_var) lw $a0, 0x8($a1) lui $v0, %hi(some_var+0x4) lw $v1, %lo(some_var+0x4)($v0) lw $a2, %gp_rel(some_var+0x4)($gp) lw $a3, %got(some_var+0x8)($gp) lw $t0, %got(static_sym)($gp) lw $t1, %lo(static_sym)($t0) lw $t9, %call16(global_function)($gp) jalr $t9 nop lw $gp, 0x18($sp) lw $t9, %call16(global_function)($gp) jalr $t9 nop lw $gp, 0x18($sp) lw $t9, %got(non_global_function)($gp) addiu $t9, $t9, %lo(non_global_function) jalr $t9 nop lw $gp, 0x18($sp) lw $t9, %got(func_arr)($gp) lw $t9, 0x4($t9) jalr $t9 nop lw $gp, 0x18($sp) lui $a0, %got_hi(some_var) addu $a0, $a0, $gp lw $a0, %got_lo(some_var)($a0) lw $a1, 0x8($a0) lw $a2, 0xC($a0) lw $a0, 0x4($a0) lui $t9, %call_hi(global_function) addu $t9, $t9, $gp lw $t9, %call_lo(global_function)($t9) jalr $t9 nop lw $gp, 0x18($sp) lw $ra, 0x10($sp) addiu $sp, $sp, 0x20 jr $ra nop .end silly_func .size silly_func, . - silly_func .globl global_function .type global_function, @function global_function: .ent global_function jr $ra nop .end global_function .size global_function, . - global_function .local non_global_function .type non_global_function, @function non_global_function: .ent non_global_function jr $ra nop .end non_global_function .size non_global_function, . - non_global_function .section .sdata .align 2 .globl some_var .type some_var, @object some_var: .word 0x12345678 .word 0x12345678 .word 0x12345678 .word 0x12345678 .size some_var, .-some_var .local static_sym static_sym: .type static_sym, @object .word 0x12345678 .word 0x12345678 .word 0x12345678 .word 0x12345678 .size static_sym, .-static_sym .globl func_arr .type func_arr, @object func_arr: .word non_global_function .word global_function .word non_global_function .word global_function .size func_arr, .-func_arr ``` -------------------------------- ### Get String Guesser Flags Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/sections/before_proc/struct.DataSectionSettings.html Retrieves the StringGuesserFlags from DataSectionSettings. ```rust pub fn string_guesser_flags(&self) -> StringGuesserFlags ``` -------------------------------- ### Create Nobits and GCC Exception Table Sections Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/context/the_context.rs.html Methods for initializing Nobits sections and GCC exception table sections via Python bindings. ```rust name: String, vram_start: Vram, vram_end: Vram, parent_segment_info: ParentSegmentInfo, ) -> Result { let vram_ranges = AddressRange::new(vram_start, vram_end); Ok(PyNobitsSection::new(self.create_section_bss( settings, name, vram_ranges, parent_segment_info, )?)) } #[pyo3(name = "create_section_gcc_except_table")] pub fn py_create_section_gcc_except_table( &mut self, settings: &DataSectionSettings, name: String, raw_bytes: Vec, rom: Rom, vram: Vram, parent_segment_info: ParentSegmentInfo, ) -> Result { Ok(PyDataSection::new(self.create_section_gcc_except_table( settings, name, raw_bytes, rom, vram, parent_segment_info, )?)) } ``` -------------------------------- ### Get Symbol Visibility Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/symbol_metadata.rs.html Retrieves the visibility setting for the symbol, if set. ```rust pub fn visibility(&self) -> Option> { self.visibility.clone() } ``` -------------------------------- ### Get Symbol Referrers Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/symbol_metadata.rs.html Returns a reference to the collection of referrers for this symbol. ```rust pub fn sym_referrers(&self) -> &Referrers { &self.sym_referrers } ``` -------------------------------- ### Initialize Data Symbol Display Settings Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/symbols/display/sym_data_display.rs.html Creates a new instance of `SymDataDisplaySettings` with default common settings. Use this to configure how data symbols are displayed. ```rust pub fn new() -> Self { Self { common: SymCommonDisplaySettings::new(), } } ``` -------------------------------- ### Initialize ExecutableSection Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/sections/before_proc/executable_section.rs.html Creates a new ExecutableSection instance after validating input bytes, ROM, and VRAM alignment. ```rust impl ExecutableSection { pub(crate) fn new( context: &mut Context, settings: &ExecutableSectionSettings, name: Arc, raw_bytes: Vec, rom: Rom, vram: Vram, parent_segment_info: ParentSegmentInfo, ) -> Result { if raw_bytes.is_empty() { return Err(EmptySectionError::new(name, vram).into()); } if raw_bytes.len() % BYTES_PER_INSTR as usize != 0 { return Err( BadBytesSizeError::new(name, raw_bytes.len(), BYTES_PER_INSTR as usize).into(), ); } if vram.inner() % BYTES_PER_INSTR != 0 { return Err(UnalignedVramError::new(name, vram, BYTES_PER_INSTR as usize).into()); } if rom.inner() % BYTES_PER_INSTR != 0 { return Err(UnalignedRomError::new(name, rom, BYTES_PER_INSTR as usize).into()); } let size = Size::new(raw_bytes.len() as u32); let rom_range = AddressRange::new(rom, rom + size); let vram_range = AddressRange::new(vram, vram + size); let ranges = RomVramRange::new(rom_range, vram_range); let instrs = instrs_from_bytes(settings, context.global_config().endian(), &raw_bytes, vram); debug_assert!(!instrs.is_empty(), "{name}, {vram:?}, {rom:?}"); let owned_segment = context.find_owned_segment(&parent_segment_info)?; let boundaries = find_functions( context.global_config(), settings, owned_segment, ranges, &instrs, )?; debug_assert!(!boundaries.is_empty(), "{name}, {vram:?}, {rom:?}"); let mut symbols = Vec::new(); let mut symbol_vrams = UnorderedSet::new(); let mut bytes_iter = raw_bytes.into_iter(); let mut instrs_iter = instrs.into_iter(); for boundary in boundaries { let local_offset = boundary.start as u32 * BYTES_PER_INSTR; let s = Size::new(local_offset); let current_vram = vram + s; let current_rom = rom + s; symbol_vrams.insert(vram); let parent_metadata = ParentSectionMetadata::new(name.clone(), vram, parent_segment_info.clone()); let word_count = boundary.end - boundary.start; let sym = if let Some(data_type) = boundary.data_type { let sym_bytes: Arc<[u8]> = bytes_iter .by_ref() .take(word_count * BYTES_PER_INSTR as usize) .collect(); ``` -------------------------------- ### Get Section Type Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/symbol_metadata.rs.html Retrieves the section type associated with the symbol. ```rust pub fn section_type(&self) -> Option { self.section_type } ``` -------------------------------- ### Get GeneratedBy Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/symbol_metadata.rs.html Accessor method to retrieve the GeneratedBy enum for the symbol. ```rust pub fn generated_by(&self) -> GeneratedBy { self.generated_by } ``` -------------------------------- ### Build Global Configuration Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/config/global_config.rs.html Clones the current disassembler state and builds the global configuration. ```rust pub fn py_build(&self) -> GlobalConfig { self.clone().build() } ``` -------------------------------- ### Get VRAM Size - Rust Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/metadata/segment_metadata.rs.html Returns the Size of the VRAM range. ```rust pub fn vram_size(&self) -> Size { self.ranges.vram().size() } ``` -------------------------------- ### Entry Implementations Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/collections/unordered_map/struct.Entry.html Methods available on the Entry struct. ```APIDOC ## Implementations ### impl<'a, K, V> Entry<'a, K, V> #### pub fn or_insert(self, default: V) -> &'a mut V Inserts a default value if the entry is vacant and returns a mutable reference to the value. #### pub fn or_insert_with(self, default: F) -> &'a mut V where F: FnOnce() -> V, Inserts a value computed by the closure if the entry is vacant and returns a mutable reference to the value. #### pub fn or_insert_with_key(self, default: F) -> &'a mut V where F: FnOnce(&K) -> V, Inserts a value computed by the closure, using the key, if the entry is vacant and returns a mutable reference to the value. #### pub fn key(&self) -> &K Returns a reference to the key of the entry. #### pub fn and_modify(self, f: F) -> Self where F: FnOnce(&mut V), Modifies the value in place if the entry is occupied, then returns the entry. #### pub fn is_vacant(&self) -> bool Returns true if the entry is vacant. ### impl<'a, K, V> Entry<'a, K, V> where K: Ord, V: Default, #### pub fn or_default(self) -> &'a mut V Inserts the default value if the entry is vacant and returns a mutable reference to the value. ``` -------------------------------- ### Get an Iterator Over Values Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/collections/addended_ordered_map.rs.html Returns an iterator over the values of the map, in order. ```rust pub fn values(&self) -> btree_map::Values<'_, K, V> { self.inner.values() } ``` -------------------------------- ### GlobalConfigBuilder Setter Methods (with_*) Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/config/global_config.rs.html Provides fluent setter methods (e.g., `with_gp_config`, `with_macro_labels`) for the GlobalConfigBuilder. These methods allow chaining configuration options and return a new builder instance with the updated setting. ```rust impl GlobalConfigBuilder { pub const fn endian(&self) -> Endian { self.endian } pub const fn gp_config(&self) -> Option<&GpConfig> { self.gp_config.as_ref() } pub fn gp_config_mut(&mut self) -> &mut Option { &mut self.gp_config } pub fn with_gp_config(self, gp_config: Option) -> Self { Self { gp_config, ..self } } pub const fn macro_labels(&self) -> Option<&MacroLabels> { self.macro_labels.as_ref() } pub fn macro_labels_mut(&mut self) -> &mut Option { &mut self.macro_labels } pub fn with_macro_labels(self, macro_labels: Option) -> Self { Self { macro_labels, ..self } } pub const fn emit_size_directive(&self) -> bool { self.emit_size_directive } pub fn emit_size_directive_mut(&mut self) -> &mut bool { &mut self.emit_size_directive } pub fn with_emit_size_directive(self, emit_size_directive: bool) -> Self { Self { emit_size_directive, ..self } } pub const fn symbol_name_generation_settings(&self) -> &SymbolNameGenerationSettings { &self.symbol_name_generation_settings } pub fn symbol_name_generation_settings_mut(&mut self) -> &mut SymbolNameGenerationSettings { &mut self.symbol_name_generation_settings } pub fn with_symbol_name_generation_settings( self, symbol_name_generation_settings: SymbolNameGenerationSettings, ) -> Self { Self { symbol_name_generation_settings, ..self } } } ``` -------------------------------- ### TryFrom for Size Implementation Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/addresses/struct.VramOffset.html Conversion from VramOffset to Size. ```APIDOC ## TryFrom for Size ### `try_from` Performs the conversion from `VramOffset` to `Size`. - **Parameters**: - `value` (VramOffset) - The VramOffset value to convert. - **Returns**: - `Result` - `Ok(Size)` on success, or `Err(ConvertToSizeError)` on failure. ``` -------------------------------- ### Get an Iterator Over Keys Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/collections/addended_ordered_map.rs.html Returns an iterator over the keys of the map, in order. ```rust pub fn keys(&self) -> btree_map::Keys<'_, K, V> { self.inner.keys() } ``` -------------------------------- ### Get Reference Count Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/analysis/referenced_address.rs.html Returns the number of other addresses that reference this one. ```rust pub fn reference_counter(&self) -> usize { self.referenced_by.len() } ``` -------------------------------- ### Expose Section Creation to Python Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/context/the_context.rs.html Wraps internal section creation methods for text, data, rodata, and bss sections to be accessible via Python bindings. ```rust #[pymethods] impl Context { #[pyo3(name = "create_section_text")] pub fn py_create_section_text( &mut self, settings: &ExecutableSectionSettings, name: String, raw_bytes: Vec, rom: Rom, vram: Vram, parent_segment_info: ParentSegmentInfo, ) -> Result { Ok(PyExecutableSection::new(self.create_section_text( settings, name, raw_bytes, rom, vram, parent_segment_info, )?)) } #[pyo3(name = "create_section_data")] pub fn py_create_section_data( &mut self, settings: &DataSectionSettings, name: String, raw_bytes: Vec, rom: Rom, vram: Vram, parent_segment_info: ParentSegmentInfo, ) -> Result { Ok(PyDataSection::new(self.create_section_data( settings, name, raw_bytes, rom, vram, parent_segment_info, )?)) } #[pyo3(name = "create_section_rodata")] pub fn py_create_section_rodata( &mut self, settings: &DataSectionSettings, name: String, raw_bytes: Vec, rom: Rom, vram: Vram, parent_segment_info: ParentSegmentInfo, ) -> Result { Ok(PyDataSection::new(self.create_section_rodata( settings, name, raw_bytes, rom, vram, parent_segment_info, )?)) } #[pyo3(name = "create_section_bss")] pub fn py_create_section_bss( &mut self, settings: &NobitsSectionSettings, ``` -------------------------------- ### Get VRAM Address Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/analysis/referenced_address.rs.html Returns the VRAM address associated with this ReferencedAddress. ```rust pub const fn vram(&self) -> Vram { self.vram } ``` -------------------------------- ### Build Overlays Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/context/builder/context_builder.rs.html Processes a vector of `OverlaySegmentHeater` to build overlay data. It calculates visible VRAM ranges for each overlay and prepares them for further processing. ```rust fn build_overlays( overlays: Vec, ) -> Result, BuildContextError> { let mut visible_ranges_for_overlays = Vec::new(); for overlay in &overlays { visible_ranges_for_overlays.push(Self::get_visible_vram_ranges_for_segment( Some(overlay.name()), overlay.inner(), &overlays, )?); } let mut overlays: Vec<(OverlaySegmentHeater, Vec>)> = overlays .into_iter() .zip(visible_ranges_for_overlays) .collect(); // ... rest of the implementation } ``` -------------------------------- ### CloneToUninit for Clone Types (Nightly) Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/addresses/struct.AddressRange.html Details the nightly-only experimental blanket implementation of `CloneToUninit` for types `T` that implement `Clone`. ```APIDOC ## impl CloneToUninit for T ### Description Nightly-only experimental blanket implementation of `CloneToUninit` for `T`. ### Constraints - `T: Clone` ### Methods #### unsafe fn clone_to_uninit(&self, dest: *mut u8) Performs copy-assignment from `self` to `dest`. ``` -------------------------------- ### Get Compiler Setting Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/sections/before_proc/struct.DataSectionSettings.html Retrieves the current Compiler setting from DataSectionSettings. ```rust pub fn compiler(&self) -> Option ``` -------------------------------- ### Get Size of Vram AddressRange Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/addresses/struct.AddressRange.html Calculates the size of an AddressRange of Vram. ```rust pub const fn size(&self) -> Size ``` -------------------------------- ### CloneToUninit Trait Implementation (Nightly Only) Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/sections/enum.SectionPostProcessError.html Details the nightly-only experimental API for `CloneToUninit`, which performs copy-assignment to an uninitialized memory location. ```APIDOC ## impl CloneToUninit for T ### Description 🔬 This is a nightly-only experimental API. Performs copy-assignment from `self` to `dest`. ### Method #### unsafe fn clone_to_uninit(&self, dest: *mut u8) Performs copy-assignment from `self` to `dest`. ### Endpoint N/A ### Parameters #### Path Parameters N/A #### Query Parameters N/A #### Request Body N/A ### Request Example N/A ### Response #### Success Response (200) N/A #### Response Example N/A ``` -------------------------------- ### Get GotGlobalEntry Initial Value Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/spimdisasm/addresses/struct.GotGlobalEntry.html Returns the initial value of the GotGlobalEntry. ```rust pub const fn initial(&self) -> u32 ``` -------------------------------- ### Create Executable Section Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/context/the_context.rs.html Creates a new executable section within the current context, ensuring the ROM address has been preheated. ```APIDOC ## POST /context/sections/text ### Description Creates a new executable section (text) using the provided settings, raw bytes, and memory mapping information. ### Method POST ### Endpoint /context/sections/text ### Parameters #### Request Body - **settings** (ExecutableSectionSettings) - Required - Configuration settings for the executable section. - **name** (String) - Required - The name of the section. - **raw_bytes** (Vec) - Required - The binary data for the section. - **rom** (Rom) - Required - The ROM address range. - **vram** (Vram) - Required - The virtual memory address. - **parent_segment_info** (ParentSegmentInfo) - Required - Information about the parent segment. ### Response #### Success Response (200) - **ExecutableSection** (Object) - The newly created executable section instance. #### Error Response (400) - **SectionAlreadyCreatedError** - Returned if the ROM address has already been used. - **SectionNotPreheatedError** - Returned if the ROM address was not preheated. ``` -------------------------------- ### DataSectionSettings Configuration Methods Source: https://docs.rs/spimdisasm/2.0.0-alpha.1/src/spimdisasm/sections/before_proc/data_section.rs.html Methods to get and set configuration properties for DataSectionSettings. ```APIDOC ## DataSectionSettings Configuration ### Description Methods to manage string guesser flags and encoding settings. ### Methods - **string_guesser_flags()**: Returns the current StringGuesserFlags. - **set_string_guesser_flags(flags)**: Updates the string guesser flags. - **encoding()**: Returns the current Encoding. - **set_encoding(encoding)**: Updates the encoding configuration. ```