rom_analyzer/console/
gba.rs

1//! Provides header analysis functionality for Game Boy Advance (GBA) ROMs.
2//!
3//! This module can parse GBA ROM headers to extract game title, game code,
4//! maker code, and region information.
5//!
6//! GBA header documentation referenced here:
7//! <https://problemkaputt.de/gbatek-gba-cartridge-header.htm>
8
9use serde::Serialize;
10
11use crate::error::RomAnalyzerError;
12use crate::region::{Region, check_region_mismatch};
13
14/// Struct to hold the analysis results for a GBA ROM.
15#[derive(Debug, PartialEq, Clone, Serialize)]
16pub struct GbaAnalysis {
17    /// The name of the source file.
18    pub source_name: String,
19    /// The identified region(s) as a region::Region bitmask.
20    pub region: Region,
21    /// The identified region name (e.g., "Japan").
22    pub region_string: String,
23    /// If the region in the ROM header doesn't match the region in the filename.
24    pub region_mismatch: bool,
25    /// The game title extracted from the ROM header.
26    pub game_title: String,
27    /// The game code extracted from the ROM header.
28    pub game_code: String,
29    /// The maker code extracted from the ROM header.
30    pub maker_code: String,
31}
32
33impl GbaAnalysis {
34    /// Returns a printable String of the analysis results.
35    pub fn print(&self) -> String {
36        format!(
37            "{}\n\
38             System:       Game Boy Advance (GBA)\n\
39             Game Title:   {}\n\
40             Game Code:    {}\n\
41             Maker Code:   {}\n\
42             Region:       {}",
43            self.source_name, self.game_title, self.game_code, self.maker_code, self.region
44        )
45    }
46}
47
48/// Determines the Game Boy Advance game region name based on a given region byte.
49///
50/// The region byte typically comes from the ROM header. This function extracts the relevant bits
51/// from the byte and maps it to a human-readable region string and a Region bitmask.
52///
53/// # Arguments
54///
55/// * `region_byte` - The byte containing the region code, usually found in the ROM header.
56///
57/// # Returns
58///
59/// A tuple containing:
60/// - A `&'static str` representing the region as written in the ROM header (e.g., "USA", "Japan",
61///   "Europe") or "Unknown" if the region code is not recognized.
62/// - A [`Region`] bitmask representing the region(s) associated with the code.
63///
64/// # Examples
65///
66/// ```rust
67/// use rom_analyzer::console::gba::map_region;
68/// use rom_analyzer::region::Region;
69///
70/// let (region_str, region_mask) = map_region(0x00);
71/// assert_eq!(region_str, "Japan");
72/// assert_eq!(region_mask, Region::JAPAN);
73///
74/// let (region_str, region_mask) = map_region(0x01);
75/// assert_eq!(region_str, "USA");
76/// assert_eq!(region_mask, Region::USA);
77///
78/// let (region_str, region_mask) = map_region(0x02);
79/// assert_eq!(region_str, "Europe");
80/// assert_eq!(region_mask, Region::EUROPE);
81/// ```
82pub fn map_region(region_byte: u8) -> (&'static str, Region) {
83    match region_byte {
84        0x00 => ("Japan", Region::JAPAN),
85        0x01 => ("USA", Region::USA),
86        0x02 => ("Europe", Region::EUROPE),
87        // ASCII representations are also common
88        b'J' => ("Japan", Region::JAPAN),
89        b'U' => ("USA", Region::USA),
90        b'E' => ("Europe", Region::EUROPE),
91        b'P' => ("Europe", Region::EUROPE), // PAL
92        _ => ("Unknown", Region::UNKNOWN),
93    }
94}
95
96/// Analyzes Game Boy Advance (GBA) ROM data.
97///
98/// This function reads the GBA ROM header to extract the game title, game code,
99/// maker code, and region information. It then normalizes the region and performs
100/// a region mismatch check against the `source_name`.
101///
102/// # Arguments
103///
104/// * `data` - A byte slice (`&[u8]`) containing the raw ROM data.
105/// * `source_name` - The name of the ROM file, used for region mismatch checks.
106///
107/// # Returns
108///
109/// A `Result` which is:
110/// - `Ok`([`GbaAnalysis`]) containing the detailed analysis results.
111/// - `Err`([`RomAnalyzerError`]) if the ROM data is too small to contain a valid GBA header.
112pub fn analyze_gba_data(data: &[u8], source_name: &str) -> Result<GbaAnalysis, RomAnalyzerError> {
113    // GBA header is at offset 0x0. Relevant info: Game Title (0xA0-0xAC), Game Code (0xAC-0xB0), Maker Code (0xB0-0xB2), Region (0xB4).
114    // The header is typically 192 bytes (0xC0), but we'll use a slightly larger safety margin.
115    const HEADER_SIZE: usize = 0xC0;
116    if data.len() < HEADER_SIZE {
117        return Err(RomAnalyzerError::DataTooSmall {
118            file_size: data.len(),
119            required_size: HEADER_SIZE,
120            details: "GBA header".to_string(),
121        });
122    }
123
124    // Extract Game Title (12 bytes, null-terminated)
125    let game_title = String::from_utf8_lossy(&data[0xA0..0xAC])
126        .trim_matches(char::from(0)) // Remove null bytes
127        .to_string();
128
129    // Extract Game Code (4 bytes, ASCII)
130    let game_code = String::from_utf8_lossy(&data[0xAC..0xB0])
131        .trim_matches(char::from(0)) // Remove null bytes, though usually not null-terminated here
132        .to_string();
133
134    // Extract Maker Code (2 bytes, ASCII)
135    let maker_code = String::from_utf8_lossy(&data[0xB0..0xB2])
136        .trim_matches(char::from(0)) // Remove null bytes
137        .to_string();
138
139    // Extract Region Code (1 byte at 0xB4)
140    let region_code_byte = data[0xB4];
141
142    // Determine region name based on the byte value.
143    let (region_name, region) = map_region(region_code_byte);
144
145    let region_mismatch = check_region_mismatch(source_name, region);
146
147    Ok(GbaAnalysis {
148        source_name: source_name.to_string(),
149        region,
150        region_string: region_name.to_string(),
151        region_mismatch,
152        game_title,
153        game_code,
154        maker_code,
155    })
156}
157
158#[cfg(test)]
159mod tests {
160    use super::*;
161
162    /// Helper function to generate a minimal GBA header for testing.
163    fn generate_gba_header(
164        game_code: &str,
165        maker_code: &str,
166        region_byte: u8,
167        title: &str,
168    ) -> Vec<u8> {
169        let mut data = vec![0; 0xC0]; // Ensure enough space for header
170
171        // Game Title (max 10 chars + null, but we use 0xA0..0xAC which is 12 bytes for safety)
172        let mut title_bytes = title.as_bytes().to_vec();
173        title_bytes.resize(12, 0);
174        data[0xA0..0xAC].copy_from_slice(&title_bytes);
175
176        // Game Code (4 bytes, ASCII)
177        let mut game_code_bytes = game_code.as_bytes().to_vec();
178        game_code_bytes.resize(4, 0);
179        data[0xAC..0xB0].copy_from_slice(&game_code_bytes);
180
181        // Maker Code (2 bytes, ASCII)
182        let mut maker_code_bytes = maker_code.as_bytes().to_vec();
183        maker_code_bytes.resize(2, 0);
184        data[0xB0..0xB2].copy_from_slice(&maker_code_bytes);
185
186        // Region Code (1 byte at 0xB4)
187        data[0xB4] = region_byte;
188
189        data
190    }
191
192    #[test]
193    fn test_analyze_gba_data_japan_code() -> Result<(), RomAnalyzerError> {
194        let data = generate_gba_header("ABCD", "XX", 0x00, "GBA JP GAME"); // Japan region code 0x00
195        let analysis = analyze_gba_data(&data, "test_rom_jp.gba")?;
196
197        assert_eq!(analysis.source_name, "test_rom_jp.gba");
198        assert_eq!(analysis.game_title, "GBA JP GAME");
199        assert_eq!(analysis.game_code, "ABCD");
200        assert_eq!(analysis.maker_code, "XX");
201        assert_eq!(analysis.region, Region::JAPAN);
202        assert_eq!(analysis.region_string, "Japan");
203        assert_eq!(
204            analysis.print(),
205            "test_rom_jp.gba\n\
206             System:       Game Boy Advance (GBA)\n\
207             Game Title:   GBA JP GAME\n\
208             Game Code:    ABCD\n\
209             Maker Code:   XX\n\
210             Region:       Japan"
211        );
212        Ok(())
213    }
214
215    #[test]
216    fn test_analyze_gba_data_pal_char() -> Result<(), RomAnalyzerError> {
217        let data = generate_gba_header("YZAB", "DD", b'P', "GBA PAL GAME"); // PAL region char 'P'
218        let analysis = analyze_gba_data(&data, "test_rom_pal.gba")?;
219
220        assert_eq!(analysis.source_name, "test_rom_pal.gba");
221        assert_eq!(analysis.game_title, "GBA PAL GAME");
222        assert_eq!(analysis.game_code, "YZAB");
223        assert_eq!(analysis.maker_code, "DD");
224        assert_eq!(analysis.region, Region::EUROPE);
225        assert_eq!(analysis.region_string, "Europe");
226        assert_eq!(
227            analysis.print(),
228            "test_rom_pal.gba\n\
229             System:       Game Boy Advance (GBA)\n\
230             Game Title:   GBA PAL GAME\n\
231             Game Code:    YZAB\n\
232             Maker Code:   DD\n\
233             Region:       Europe"
234        );
235        Ok(())
236    }
237
238    #[test]
239    fn test_analyze_gba_data_europe_char() -> Result<(), RomAnalyzerError> {
240        let data = generate_gba_header("IJKL", "ZZ", b'E', "GBA EUR GAME"); // Europe region char 'E'
241        let analysis = analyze_gba_data(&data, "test_rom_eur.gba")?;
242
243        assert_eq!(analysis.source_name, "test_rom_eur.gba");
244        assert_eq!(analysis.game_title, "GBA EUR GAME");
245        assert_eq!(analysis.game_code, "IJKL");
246        assert_eq!(analysis.maker_code, "ZZ");
247        assert_eq!(analysis.region, Region::EUROPE);
248        assert_eq!(analysis.region_string, "Europe");
249        Ok(())
250    }
251
252    #[test]
253    fn test_analyze_gba_data_japan_char() -> Result<(), RomAnalyzerError> {
254        let data = generate_gba_header("MNOP", "AA", b'J', "GBA JP CHAR"); // Japan region char 'J'
255        let analysis = analyze_gba_data(&data, "test_rom_jp_char.gba")?;
256
257        assert_eq!(analysis.source_name, "test_rom_jp_char.gba");
258        assert_eq!(analysis.game_title, "GBA JP CHAR");
259        assert_eq!(analysis.game_code, "MNOP");
260        assert_eq!(analysis.maker_code, "AA");
261        assert_eq!(analysis.region, Region::JAPAN);
262        assert_eq!(analysis.region_string, "Japan");
263        Ok(())
264    }
265
266    #[test]
267    fn test_analyze_gba_data_usa_char() -> Result<(), RomAnalyzerError> {
268        let data = generate_gba_header("UVWX", "CC", b'U', "GBA US CHAR"); // USA region char 'U'
269        let analysis = analyze_gba_data(&data, "test_rom_us_char.gba")?;
270
271        assert_eq!(analysis.source_name, "test_rom_us_char.gba");
272        assert_eq!(analysis.game_title, "GBA US CHAR");
273        assert_eq!(analysis.game_code, "UVWX");
274        assert_eq!(analysis.maker_code, "CC");
275        assert_eq!(analysis.region, Region::USA);
276        assert_eq!(analysis.region_string, "USA");
277        assert_eq!(
278            analysis.print(),
279            "test_rom_us_char.gba\n\
280             System:       Game Boy Advance (GBA)\n\
281             Game Title:   GBA US CHAR\n\
282             Game Code:    UVWX\n\
283             Maker Code:   CC\n\
284             Region:       USA"
285        );
286        Ok(())
287    }
288
289    #[test]
290    fn test_analyze_gba_data_too_small() {
291        // Test with data smaller than the minimum required size for analysis.
292        let data = vec![0; 50]; // Smaller than 0xC0
293        let result = analyze_gba_data(&data, "too_small.gba");
294        assert!(result.is_err());
295        assert!(result.unwrap_err().to_string().contains("too small"));
296    }
297}
rom_analyzer/console/gba.rs

rom_analyzer/console/
gba.rs
