How do I USE WinRom?

What would you like to know more about?

General:

Specifics:

 


Give me a quick overview, please.

When you first run WinRom, you see an empty window with a toolbar and not much else.   To get started, you'll either start a new project, or open a previously saved one.   This is done in the File menu, under New and Open, respectively.  If you start a new project, you will need to specify which Template File to use.  DON'T confuse choosing a template file with opening one of your previously saved projects, or you'll get really confused.

Type values into the edit boxes which are displayed, or leave the default values if they are correct (DO NOT ASSUME they're correct unless you typed them yourself).  If you enter a value which WinRom doesn't understand, the contents of your edit box will turn RED until you figure out what's up and fix the problem.   Red values are not stored or remembered when you save the file, so you should fix errors as soon as you see them.

At any time, you can save your work to a WinRom file (*.wnr) to use again later.   That way, everything you just typed won't have to be repeated.  You can always open a saved document, modify it, and re-save it if you want.

To get your project out of WinRom and on paper or a chip, you need to use the Export command under the File menu.  Exporting to ASCII (human readable) or Intel MCS-86 (hardware readable, primarily) is possible.  WinRom will change the Status bar's message to "Working..." while it's exporting.  Depending on how large your ROM is, and your computer's speed, exporting could take a minute or more.


Starting a new ROM project.

Click on the "New" button or use the File->New... command to start a new project.  WinRom will prompt you to specify a Template File.

The Template File has to be there when you start a new project, so WinRom can find out details about the ROM you want to program, information on what each field means, and which information it needs to request from the user.  The template is every bit of configuration that goes into a project.  If you want to change the way the program treats values in any way, edit the Template File.

You may open as many new projects as you want.  Each one will appear in its own window.


Opening a saved  project.

Opening a saved project does not require a template, since that information is already in the saved file.  This is just a way to pick up where you left off last time you were working, just like any other kind of saved document.

Use the "Open" button or use the File->Open... command to open a previously saved project.  Once the project is open, you can continue with it as if you had just typed it all in right now.

You may open as many saved projects as you want.  Each one will appear in its own window.


Interacting with the multi-page dialog.

Once you have a project open, you work on it by entering values into the dialog window.   Click in a window to edit there, or use the Tab key to move from field to field.   The edit boxes behave like other familiar edit areas in Windows.  Clipboard commands (copy, cut, paste) all work either by the toolbar buttons, the Edit menu, or right-clicking inside the edit box.

You can type most characters into string fields, but only as many as allowed by the template file for that field.  Numeric fields accept data as base-16 (if you prefix it with "0x") or base-10 (if you don't).

If you enter a value which WinRom doesn't understand, it will paint the text RED to let you know something needs to be fixed.  Red values are not saved or exported, so make sure you fix errors as soon as you see them.  If saving or exporting a project with an error in it, WinRom will use the last good value which was entered for the field with the error.

Possible problems are:

You may see arrow icons on the right side of the dialog window.  This means that there are more fields to edit either below or above your current position.  Click on the arrows with the mouse to move through the dialog.  It's a good idea to look at all the values at least once, unless you wrote them yourself and are sure they're all right.

The usual Clipboard functions (copy, paste, cut) work in the edit fields the same way as in most Windows applications.  You can use hotkeys (ctrl+ c, v, or x), the Edit menu, or you can right-click in the edit box to activate these features.  You can undo/redo the last edit action you performed in your project by typing ctrl+z or using Edit->Undo.  This will undo or redo your last action, no matter where in the project you made the change.  In other words, if you changed something in an edit box which is now off the screen, you will not see the effect of undo-ing it, even though the action IS being performed.

When working on your project, you may want to look at more than one part of the dialog at a time.  You can use the "New Window" command (under the Window menu) to open copies of any project.  When you make changes in any of the copies' windows, all the other windows will be updated instantly.  (Try this, it's fun).  Notice that if you enter an impossible value into a field, it turns red, and the other windows are NOT updated.  This is because the computer refuses to take you seriously until you start making more sense.


Looking at all the ugly details.

By default, WinRom only shows you fields in the ROM that you can change.  If you want to see what else is going on, you can view ALL the fields by un-checking "Useful Pages Only" in the View menu.  The unchangeable fields will be grayed out so they cannot be edited.

Another way to look at all the fields is to Export your project to ASCII and then print it out.


Saving your work so next time will be faster.

At any time, you can save your project, by using the "Save" button, or the Save commands under the File menu.  Saving your project is NOT the same as Exporting it for the ROM programmer.  The files made by saving your project (*.wnr) are readable by WinRom only.  They exist to make your life easier. 

For example: If all AXTR boards are similar except, say, for the serial number, you can type in all the fields, save the project as AXTR.wnr, and then open that project each time you want to program an AXTR ROM.


Exporting a project to ASCII format.

If you want to see a detailed report of what WinRom will place at which addresses, you can Export your project to an ASCII text file (under File->Export).  This produces a text file which can be read by an editor or printed out on any printer.  The exact format is currently set up to be most useful for VME ROMS and Tim in particular.   Across the top of the page, the headings are:


Exporting a project to Intel MCS-86 format (i.e. what this program is FOR)

This is the whole point of why you're using WinRom.  When you're ready to program the chip, select this command (under the File->Export menu).  It will produce output that is readable by the ROM programmer (code 88).  The file is stored in text format, but unless you're familiar with the Intel MCS-86 format, it might not make any sense to read.  I will not duplicate the format instructions here.  I learned how to output this format correctly by reading the Appendix of the ROM programmer's manual.

The file produced will be much larger than an ASCII Export because every unspecified location between fields is filled with zeros.  Also, every byte in string fields that is unspecified (i.e. when the string is shorter than the maximum length) will either be filled with zeros or spaces, depending on how the template file is set up.


What do I do about errors?

If you encounter any errors while running WinRom, a message will be displayed giving you an idea of what went wrong.  These vary in how useful they are to you, and how bad they are for your project.

BAD news first:

If you see errors like this, it means that either I have a bug in my program, or you've done a no-no which I don't have an error-checking routine to handle.  Try to contact me, gj-bell@uiuc.edu or someone else who knows about this program on a deep level.  These errors are pretty useless in helping you determine what's wrong.  They are mostly generated by Windows and mean that I haven't done a good enough job debugging or error-handling.

NOT so bad ones:

These errors are generated by WinRom to let you know that something isn't as expected.   Most often, you have an error in your Template File, or a file you specify could not be written to or found because something else is using it or it doesn't exist.   Stuff like this is pretty easy to fix, so don't sweat it.  If you get stuck, ask someone who's used the program before, or contact me, gj-bell@uiuc.edu.