
  £Hex`Debug`Monitor ("Hexmon") Program User Guide
   Preliminary Documentation, May 1994

 () 1994 Esquimalt Digital Logic Inc. All Rights Reserved.


   £Orientation

The system debugger is for use by software developers and others whohave a thorough working knowledge of OMEn and computers systems ingeneral. Users are advised not to run Hexmon, or at least not to useit to write directly to memory, without knowing the ramifications ofthe operation being performed. Hexmon is provided in the Systemfolder for ease of access during debugging operations.

This debugger dates from the early '80s on a 6809 system. Theinterface is somewhat unusual, but it allows access to memory and I/Oports in a direct non file`oriented manner different from all otherOMEn utilities.

Looking at the Hexmon window, the "Commands" area is at the top, andthe memory display occupies the rest of the window. At the left arethe addresses of the locations being viewed. Towards the right is thecontent of that memory location, viewed in hexadecimal as 16 bitwords. At the far right is the same contents viewed as two ASCIIcharacters.

"Hexmon" takes single keystroke commands. Clicking on the appropriateword in the command area at the top of the window also performs thesame function, but not all functions are available by mouse clicks.Several commands not shown in the command area can only be accessedby keyboard.

Commands which take a numeric parameter obtain it from the value mostrecently entered, which is shown in the center of Hexmon's display aseight hexadecimal digits instead of four. Values are typed in inhexadecimal.
It is important to remember this sequence: enter the numberfirst, ¥then¤ select the desired function. For example, to search forthe bytes "$F12345", type the number and make sure the data numbersays $00F12345, ¥then¤ press "S" to search from the current address. 

In addition, addresses may be dragged into Hexmon from other sourcesusing the mouse.

Hexmon has a "Help" window (just type <H>) that explains most of itsfeatures and operation in brief on the screen. As with all OMEnsoftware, pull the Hexmon window to the front to make sure thatkeystrokes are received by the Hexmon program.
 £Hexmon Commands

Here is the list of commands accepted by Hexmon.


-- Entering new addresses --

The commands below allow for absolute positioning in memory or formovement relative to the present location.

<ENTER>View address given in data
<L>Keeping same upper 16 bits, view address given in Lower
16 bits of data.
<+>add the value given in data to the address
<->subtract the value given in data from the address

<>The DownArrow key advances Hexmon's current address to
the next word of memory past the current word.
<>UpArrow puts Hexmon's address back by one word.

<G>Go to. This jump indirect" command accesses the current
word of memory and the word following as a 32 bit address
and jumps the view to that address. This is useful for
locating a memory allocation from its allocation handle
address, instead of having to type the digits visible in
the view and <ENTER>.

    -- Storing Data into Memory --

Hexmon always writes 16 bit words of data, which is either useful orannoying depending on the size of the actual desired write.

<SPACE>Write the data into the current location and then advance
the address to the next word in memory.
<X>Write the data into the current location without changing
the current location. Useful for I/O areas where advancing
might cause a bus error. (In I/O areas it is sometimes
neccessary to shrink the window to one line displayed in
order to avoid bus error locations.)


   -- Searching for binary values in memory --

Sequences of one, two, three or four bytes may be located in memory.Search is always from the current memory location upwards. The firstbyte of the sequence must be non-zero.

<S>Search for the sequence given in data. Typing
"000000AB<S>" would search for the next occurrance
of the byte AB hex. "00152F3Dew to those addresses. This can be highly usefulfor debugging software under development by allowing the programmerto view items such as the stack (user or supervisor), items pointedto by any register, and the code being executed. (On the wish list isa disassembler for viewing the code in assembly language format. Adisassembler that understands and names OMEn system calls and I/Ocalls would be extra useful.)

In addition to import of values, Hexmon can export its currentaddress or the current data (t address import sources are file directories andregisters in the crash-debug window.

When a file is dragged in, Hexmon's view address jumps to the head ofthat file. Hexmon does not, however, read in the file if it is ondisk; it simply points to the file's header. In conjunction with thefile header definitions, programmers can inspect file headers toascertain that they contain the appropriate information for the file.

Dragging in addresses from the crash window of a program beingdebugged jumps the view to those addresses. This can be highly usefulfor debugging software under development by allowing the programmerto view items such as the stack (user or supervisor), items pointedto by any register, and the code being executed. (On the wish list isa disassembler for viewing the code in assembly language format. Adisassembler that understands and names OMEn system calls and I/Ocalls would be extra useful.)

In addition to import of values, Hexmon can export its currentaddress or the current data (the 8 digit number). To export thecurrent address, drag it from the left side of Hexmon's display area.To export the value typed in, drag from the right hand side.

The most useful current places to drag addresses and values to are toregisters in the crash window and to the background window.

Dragging to the crash window can change a register to a new value fordebugging. Unfortunately, the "access address" does not currentlyaccept new values, so it is not possible to change this and proceedafter a bus error or address error.

Dragging to the background window simply prints the value on thescreen in decimal; a quick means of converting hexadecimal todecimal.


£Bus Error and Address Error Recovery

Most programs which execute a bus or address error end up at thecrash window. Hexmon changes the vector of these errors for itself tospecial handlers which allow it to recover from them. When an erroris presented, such as an address that causes a bus error, a specialwindow opens up showing the address with up arrows () above it anddown arrows () below it. Clicking on the appropriate arrow increasesor decreases that digit of the address until an address is found thatdoesn't cause a bus error; then the window exits back to the regularHexmon window.

Hexmon operates in supervisor mode, so it has access to addresseswhich may cause bus errors in user mode programs, depending on themake and model of the computer. (For example, Atari computersgenerate a bus error with any user mode access of vector space,protecting it from most errant programs.)

In the case of I/O port addresses, it sometimes occurs that addressesboth before and after the I/O port will cause bus errors. In thiscase, Hexmon's window must be shrunk so that there is only one linein the data display part of the window in order that that be the onlyaddress accessed in displaying the window. Use the <X> command towrite to the port without advancing to the next word. The bus errorhandling feature has been used to easily locate all the video I/Oregisters in one particular computer model.
 