prepare_defs.py - aalesv/2boost GitHub Wiki

prepare_defs.py - Prepare XML definitions for RomRaider from a readelf symbol dump

   prepare_defs.py [OPTION]... -t TEMPLATE [INPUT] [OUTPUT]

Converts a RomRaider XML definition template into an XML definitions file by populating it with symbol information from a readelf output. readelf - the GNU tool for displaying information about ELF files - is typically invoked with: readelf --wide -s <binary_file>

The expected input format is the symbol table listing printed by readelf. Example of readelf output:

       
       Symbol table '.symtab' contains 464 entries:
          Num:    Value  Size Type    Bind   Vis      Ndx Name
            0: 00000000     0 NOTYPE  LOCAL  DEFAULT  UND
            1: 0008f000     0 SECTION LOCAL  DEFAULT    1

A leading empty line, a comment line starting with "Symbol table", and the column header line are automatically skipped when reading from standard input. If an input file is provided via -i, those header lines must be removed manually before processing.

The template must be a valid XML file that follows RomRaider’s definitions schema. The tool uses lxml Python binding to parse the template and modifies it according to the supplied command line options. The resulting XML is not a completely valid definitions file; the user should examine and correct it manually (see CAVEATS).

   -i, --input=<filename>
          Read from given file instead of standard input.
          The file should contain the raw output of readelf.

   -t, --template=<filename>
          (required) Path to the RomRaider XML definitions
          template.

   -o, --output=<filename>
          Write output to file instead of standard output.

   --rombase=<string>
          Set the base attribute of the <rom> element to the
          given string. If omitted, the attribute is left
          unchanged.

   --internalidstring=<string>
          Write the given string into both the
          <internalidstring> tag and the <xmlid> tag. If
          omitted, those tags are left unchanged.

   --set-attribute=<xpath> <attr> <value>
          Search for all elements matching the XPath
          expression and set the attribute named <attr> to
          <value>. This option can be repeated multiple
          times.

   --default-output-attribute-name=<string>
          Set the default value of the output-attribute
          attribute (used when that attribute is absent in
          the template). Default is "data".

   --default-output-attribute-value=<string>
          Set the default value for the output-attribute
          attribute. No default value is defined.

Example 1: Process readelf output from a file, using a template, and write result to a file:

prepare_defs.py -i symbols.txt -t defs_template.xml -o romraider_defs.xml

Example 2: Pipeline readelf output directly into the tool, setting ROM base and internal ID string:

readelf --wide -s my_rom.bin | prepare_defs.py -t template.xml --rombase="32BITBASE" --internalidstring="MYROM_v1.0" > my_defs.xml

Example 3: Use --set-attribute to set data attribute of all tags where attribute id1 equals to cel_hack2_enable

readelf --wide -s my_rom.bin | prepare_defs.py -t template.xml --set-attribute "//*[@id1='cel_hack2_enable']" data "12 34 56 78" -o out.xml

   0   Success
   1   Error (e.g., missing template, invalid XML, read failure)

The tool modifies the template XML by applying command‑line options that directly set or override specific attributes:

• sanitizer attribute contains the regular expression which is applied to <xmlid> and <internalidstring> elements' content.
• internalidaddress tag set to address of VERSION variable.
• If id attribute is set for tags <table> and <state> and it's equal to object name taken from readelf output:
  • If it starts with _CFG_ or _tbl, storageaddress attribute of this tag is set to address, taken from from readelf output.
  • If it starts with _tbl and ends with _x_axis, sizex attribute of parent tag is set. sizex = object_size / 4
  • If it starts with _tbl and ends with _y_axis, sizey attribute of parent tag is setsizey = object_size / 4
• If id-extended attribute is set for any tag and it's equal to object name taken from readelf output:

  • Attribute named with output-attribute value is set to value of output-attribute-value attribute.

  • element-size is used in calculations; if unspecified, it set to 4.

  • output-attribute-value can contain following variables:

    Variable name	Variable meaning
    {address}	address of object
    {address_movi20s}	address of object prepared for movi20s instruction (only for SH72531 CPU, see CPU manual for details): address >> 8. Only addresses up to 0x007FFF00 are supported for now.
    {address_split2}	address split with spaces by groups of two: deadbeef -> de ad be ef
    {name}	name of object
    {number_of_elements}	number of elements, number_of_elements=size/element_size. Doesn't check if they are evenly divisible.
    {size}	size of object in bytes

The output file is not a valid RomRaider definitions file. The user must manually inspect and correct the generated XML before using it with RomRaider. The tool does not validate the schema; it only populates the template.