Template Files: Changing how WinRom works

Well, you may notice that every other help page points here sooner or later.   That's because ALL the configuration information for this program is dictated by template files.  If you want to have any measure of control over how WinRom works, you have to understand these hopefully straightforward creatures.  If, on the other hand, you're just trying to USE the program the way it is, and don't need to configure it or change what type of ROM it programs, etc. then you can probably get away without reading any of this.

Sections:


Look at the default first

WinRom comes packaged with a file called "default.rtm" (the rtm stands for ROM template).  This file may have been changed by you or people you know.  But assuming that it's fresh out of the box, this file is an excellent example of how the things work.  I recommend having a copy of default.rtm open while reading the rest of this page.


General formatting tips

In general, spaces and tabs are unimportant until the Value and Description fields.   The program reads the address, number of bytes, etc. as single words, but when a string value or a description is read in, it is done as a multi-word string.  In other words, you can space your first several fields any way you want with no visible effect.  But changing the format of the Value or Description fields will have a corresponding change in your project.

LINES are extremely important.  The start of a new line means the start of a new command or memory chunk.  Don't let your descriptions wrap from one line to the next, or you will BREAK the project.  Unlike many programming languages, the format of the template file is a little rigid, because the reader function is a great deal less sophisticated, and much easier to confuse.


Memory chunks

Memory chunks are the real meat of template files.  Each memory chunk line specifies what to put into some chunk of the ROM's memory.  There are several fields, all are mandatory.  A Memory Chunk statement must all fit on one line.  Do NOT let it wrap to other lines, or the result will be confusing to WinRom.

Start Address

The Start Address is the first ROM memory location where this chunk is to be stored.   It must be in HEX (base-16), prefixed with a "0x".  Memory chunks MUST be specified in ascending order of Start Address.

Number of bytes

This is the number of bytes taken up by the memory chunk.  This value must be specified in DECIMAL (base 10).  In numeric values, 0x00's will be added to most significant positions if the user inputs a value which fits into less than the maximum byte number.  Strings are padded on the end with either 0x00's or 0x20's depending on the data type.  If the number of bytes for a string variable is greater than 1024, WinRom will allow its edit box to accept newline characters and other multi-line type of things.  This is with the expectation that very long strings will likely be documents, while shorter ones are probably not.

Changeable?

This field can have exactly three values: "yes", "no", and "gen".  Yes means this field should be changeable by a user running WinRom with this template.  It will be displayed in an editable box.  No means this value is hard-coded and should not be user-configurable.  It will be visible but not changeable if the user un-checks "Useful Pages Only" in the View menu.  Gen means this value will be generated by WinRom.  So far, the only memory chunks generated like this are the checksum, and the total ROM length (see slash commands below).

Data Type

This field can have exactly three values: "num", "string", and "string20". 

Default Value

This is the value which the memory chunk will have.  If the chunk is changeable, the user can alter this value through WinRom.  If the chunk is a number, this field MUST be a hexadecimal (base 16) number prefixed with "0x".  Note that NO error checking is done on the validity of this default value, so if you put something impossible here, don't come crying to me later.  For string chunks, every word until   "##" is read will be part of the Default value. 

Please take a look at default.rtm for examples of all these types.

Description

The description is text which will appear over the edit box for this chunk, as well as in the ASCII dump file (for changeable fields).  The description MUST start with the characters "##".  From that point, every character until the end of the line will be read as the description.  Do not let your descriptions wrap to the next line, because when the program sees a newline character, it stops reading and begins the next memory chunk

Please see default.rtm for many description examples..


Slash commands (/)

These commands are the way to give WinRom information on how to perform its automated tasks.  Currently, the only such tasks it can perform are calculating the ROM's checksum, and calculating the total length of the ROM.  Both of these things are required for VME ROM's. 

Slash commands can be located at any line in the file, but they must be the only thing on the line, and the slash (/) must be the first character on the line.

/checksum    0

The checksum command tells WinRom which memory chunk to store the checksum result in.   0 means the first chunk, 1 means the second, etc.  This value will be calculated by summing all the bytes in the ROM, (keeping only the least significant byte) and taking the 2's complement of that result.  Note that for checksumming to work, you must have a Memory Chunk entry for the checksum to be stored in.

/length        1         leftshift    2         3

The length command tells WinRom various details about how to calculate the ROM's total length, and how to store that value in a Memory Chunk. 

So, why go through all that garbage?  Well, VME needs the REAL length to be leftshifted by 2 and added to 3 in order to make sense, because of the way it addresses the ROM.  In short, we're translating the number from the real value to what VME believes is the real value.  This is what we would expect to be correct, since VME controlled software will be the thing which reads this value later.  Note that you must have a Memory Chunk entry for the length to be stored in.


Comments

Any line in the template file beginning with a "#" character is treated as a comment.  The entire line is discarded by the reader and not interpreted.  This can be useful to humans.