Search RomRaider

RomRaider

Documentation

Community

Developers



  • View Page
  • Page History/Versions
  • Print Page

Editor XML Reference Guide

The Editor definition is used by RomRaider’s Editor to present to us humans a familiar representation of what the car’s engine computer understands as data inputs to machine code which allows it to operate the engine within a defined set of parameters.

The Editor definition is written in ASCII text using Extensible Markup Language (XML) format, the basic layout of an Editor definition file is:
<roms>

<scalingbase>
<scalingbase>
… more as required
<rom>
<romid>
<table>
<table>
… more tables as required
</rom>
<rom>
<romid>
<table>
<table>
… more tables as required
</rom>
… more rom as required
<rom>
<romid>
<table>
<table>
… more tables as required
</rom>

<roms>

Hosting Definitions Online

Recent versions of RomRaider support the xml tag x-include. This allows splitting definitions into multiple files or loading them from a server. The following xml shows an example:

<?xml version=“1.0” encoding=“utf-8”?>

<xi:include href=“<link-to-remote-xml-file>” xmlns:xi=“http://www.w3.org/2001/XInclude”>

<xi:fallback>
<xi:include href=“<path-to-local-fallback>”></xi:include>
</xi:fallback>

</xi:include>

The link to the remote xml file can be hosted on Github for example, where you can link the raw xml file from master. All users will automatically receive an updated version of the definition if they are online. If they are offline the local fallback will be loaded. Via File/Export you can export the currently loaded definition, which you can use to update your local copy once you notice a new version has been released on the remote server.

The <roms> Element

There is only one <roms> element in an Editor definition file. This tag is the first in the file with the closing tag at the end of the file to complete the element. Within the <roms> element optional global scaling elements <scalingbase> and <rom> elements are defined as required.

Global Scaling Elements <scalingbase>

A scale is a means of converting the raw machine code data into a value a human can understand, such as temperature in C or F, or engine speed in revolutions per minute, etc.
<scalingbase> elements are optional.
Their purpose is to define the most common attributes of a scale. We can reference this <scalingbase> when we create a table element to view the computers data. Each <scalingbase> has a unique name and the name is how a <scalingbase> is referenced in a table definition. The attributes of the <scalingbase> element are:

<scalingbase
category
name
units
expression
to_byte
format
coarseincrement
fineincrement
min
max
/>

When a <scalingbase> is created it has some default values which can be changed by setting new values for the attributes. The defaults are:

  • category= “Raw Value”
  • name = “Raw Value”
  • units = “raw value”
  • expression = “x”
  • to_byte = “x”
  • format = “#.##”
  • coarseincrement = 2
  • fineincrement = 1
  • min = 0.0
  • max = 0.0

Of these attributes, the name, expression, to_byte and format would be the minimum items to define as the other attributes can be modified if required when a table is defined.

category = the category is used to group like scales, such as Imperial, Metric, etc., this is the value that appears in the Table Tool bar scale selector list
name = the name this <scalingbase> will be referenced by and must be unique within the entire definition
units = the units for the system of measure that the expression converts the raw computer data to
expression = the formula that converts the raw computer data to a human readable value
to_byte = the formula the converts the human readable value to raw computer data
format = the format of the number for the human readable value
coarseincrement = the amount to coarsely adjust the data value when pressing the table’s course adjustment buttons
fineincrement = the amount to finely adjust the data value when pressing the table’s course adjustment buttons, this should corelate to the smallest change that the computers raw data value will accept
min = when coloring that table data use this minimum (can also be auto determined by the Editor)
max = when coloring that table data use this maximum (can also be auto determined by the Editor)

For example:
<scalingbase name="engineSpeedRpm" units="RPM" expression="x*.1953125" to_byte="x/.1953125"
  format="#" fineincrement="50" coarseincrement="100" />

The <rom> Element

Within the <rom> element we define all the unique parameters that will present a view of the engine computers’ data.
Each <rom> is unique to the engine computers’ make, manufacturer, memory model and processor version.
For example, early Subaru ECUs used Motorola 68HC16Y5 which have a 16-bit processor, 192KB of ROM and are little endian. Later ECUs were developed with Renesas SH7055 32-bit processors which are big endian. This information is captured in the <rom> and the <table> elements inside.

The <rom> element has one attribute by the name of “base”. If a <rom> element has no “base” attribute then all the information about the particular ECU is contained within.
If the “base” attribute is present, it will have a value of another <rom> element’s <xmlid> value. When a “base” is identified the <rom> that is identified becomes the basis on which this <rom> is created. This is called base ROM inheritance.
Inheritance is used widely within an Editor definition file when many <rom> elements exist.
In this way a base definition <rom> can be created which will describe in general all Motorola 68HC16Y5 16-bit processor based ECU versions. Using a base means a table only has to be defined once, but can be used to create map views for many different versions of similar ECU versions as car manufacturer refines the engine operating code and maps. A <rom> with a “base” can also refer to another <rom> that itself has a “base” and so forth, until a <rom> with no “base” is encountered.

For example, a <rom> and another with a base:

<rom>
<romid>
<xmlid>16BITBASE</xmlid>
<rom base=“16BITBASE”>
<romid>
<xmlid>A4TF520F</xmlid>

The <romid> Element

The <romid> element contains additional elements that uniquely identify the <rom> that contains it.

The <romid> has no attributes but contains these elements:

  • xmlid
  • internalidaddress
  • internalidstring
  • caseid
  • ecuid
  • make
  • market
  • model
  • submodel
  • transmission
  • year
  • flashmethod
  • memmodel
  • filesize
  • obsolete
  • version
  • author

xmlid = a unique identifier within the definition file for the parent <rom> element, base= references this
internalidaddress = the hexadecimal address within a .bin or .hex file that the file identifier is found at
internalidstring = the string of text located at the internalidaddress location, also known as the calibration ID or CAL ID
caseid = the part number found on the engine computer hardware module
ecuid = the value that identifies the engine computer to a data logger, ECU ID
make = make of the car this calibration ID is found in
market = the market of this car, ex. USDM, EDM, JDM, etc.
model = car model
submodel = car sub-model, such as GT
transmission = transmission type, ex. AT, MT, CVT, etc.
year = four digit model year
flashmethod = the kernel module name used to flash the engine computer with, typically refers to EcuFlash methods
memmodel = ROM memory size in kBytes
filesize = the size of the .bin or .hex file in kBytes
obsolete = an indication that this CAL ID has been superseded
version = (New) the version of this definition
author = (New) the author(s) of this definition

The <table> Element

The table elements creates a table at a specific memory location. It allows you to make the changes to the binary. There are multiple table types available:

  • 1D Tables
  • 2D Tables
  • 3D Tables
  • Switches
  • BitwiseSwitches

1D tables can be seen as a series of data or a single scalar value, like a rev limiter. A 2D table has an additional Y-Axis on top, which puts the table values in relation to the specified Y-Axis. This could be a deadtime table, which maps voltages to deadtimes in ms. A 3D table has both an X and a Y-axis. X and Y axis are typically 1D tables themselves (since they are a series of data), but it is also possible to use static X- and Y-axis. A static axis contains hard-coded axis values within the definition, so it does not reference memory locations inside the binary file. Ignition- and Fuelmaps are typically 3D tables, with RPM and load as axis.

Switches can be used to set specific memory locations to predefined values, where you define data for the enabled and disable state. This is often used to en- or disable specific functions within the ECU, such as OBD trouble codes for example.

Bitwise Switches allow you to toggle specific bits within a byte, this is useful for changing control bits for MS41 for example.




Forum

RomRaider Forums

Join our forums, the best place to find help and answers!





Donate


RomRaider is developed and supported by volunteers working on their own time. To support their efforts please consider making a donation.





Page last modified on April 19, 2022, at 05:31 PM
Powered by PmWiki