MBARI OASIS Mooring Guide

OASIS Driver Patches

Building and Installing Hot Patches

Overview

Some space (24 Kbytes typically) is allocated in the OASIS RAM which may be used to load code 'on the fly', outside of the ROM. Its intended use is to replace faulty drivers in the field, or load utilities that are not critical to the mooring operation to conserve ROM space. The space has occassionally been used to host drivers that would not fit into ROM. It is important to note that the patch space is volatile, and will be cleared during a Reset All, so any code placed there are at risk of being removed at any time.

The procedure outlined below describes how to build and install a 'Hot Patch'.

Building a Hot Patch

First, a patch must be built and linked with the OASIS ROM image. Here, we will make a patch for the M2 ROM, adding driver foo with source code in foo.c, driver function foo_drv() and wakeup function foo_wake(). It is assumed that the ROM image was built in /oasis/src and there is are directories /oasis/src/patch, and directories /oasis/src/patch/m2 with makefiles to build the patch:

1. Copy to /oasis/src/patch/ :
   start.s
   foo.c
   
2. Delete from /oasis/src/patch/ :
   *.obj
   *.lst
   *.M96
3. Delete from /oasis/src/patch/<deployment>/ :
   foo
   foo.hex
   foo.M96
   
4. Edit /oasis/src/patch/makefile
   Add rule for foo.obj
   
5. edit /oasis/src/patch/<deployment>/ makefile
   RAM() location 100h in size, beginning at the location of the symbol PATCH_DATA in /oasis/src/<deployment>.M96.
   ROM() location occupies A000-AFFF, divided among all hot patched drivers
   
6. cd /oasis/src/patch/
7. make foo foo.hex
   Generates foo, foo.hex, foo.M96
   

Generating the Hot Patch Upload File

Once the driver has been made, the hex record output and oasis commands to load the driver are placed in a text file, which may be uploaded and executed by OASIS. The load command is first; it expects to be followed by the hex format driver code (foo.hex), followed by a drvadd command, which expects the driver name (foo), the driver memory location, the driver wakeup function memory location (contained in foo.M96). The drvadd command will also execute a dp foo, which will expect the driver parameters values to be set. The parameter-value pairs are at the end of the foo.txt file:

1. Make foo.txt file:
   load
   [insert foo.hex contents here]
   drvadd foo foo_drv_offset foo_wake_offset (look for foo_drv and foo_wake in .M96 file)
   foo_parm_number
   foo_parm_value...
   
   

Installing the Hot Patch

Finally, the patch is installed by performing an ASCII file upload at the OASIS prompt:

1. Upload file to OASIS:
   from Procomm:
   Press CTL-A UPARROW
   Select ASCII
   Enter the path to foo.txt
   
   from Telix:
   Press PGUP key
   Enter the path to foo.up
   
   from Hyperterminal:
   Select Transfer File from the menu bar
   Select Text File... from the menu
   Find and select foo.up
   

The load command at the beginning of the file will be executed on the OASIS command line, causing OASIS to begin to load and locate the hex record portion of the file. When the hex records have been loaded, the drvadd command will execute, adding the driver to the driver list. The drvadd command then prompts for driver parameters in parameter-number/parameter-value pairs, separated by a carriage return. A carriage return input for a parameter number or timeout ends the parameter input.

A similar method is used to add commands to the OASIS user interface, e.g., shutcal. In this instance, the loading of hex records is the same as it is for driver hex records. The cmdadd command is executed, which prompts for the types of three command line parameters.

It may be more convenient to do these procedures manually, since the timing over the packet radio is often such that the input parameters for the drvadd or cmdadd are missed. To do this,

1. Execute the load command from the OASIS command line
   
   
2. Do an ASCII transfer of the .HEX file
   
   
3. When the upload is complete, execute the drvadd or cmdadd command (whichever is appropriate) from the OASIS command line and input the required information at the prompts.
   
   
4. If there are problems entering the driver parameters, it is possible to try again using dp <driver name>
   
   
5. POWER USERS ONLY TIP: When the packet link is especially poor, it is sometimes easier to use the d (display memory) command to locate the driver list (it begins at the symbol DRV_LIST from the .M96 file) and the s (set memory) command to manually set the values of the driver parameters, remembering that Intel byte order is used. Check your input using dp <driver name>. **USE THIS METHOD ONLY AS A LAST RESORT, AND ONLY IF YOU KNOW WHAT YOU ARE DOING**
   

*may be done manually after file upload
** other terminal programs do not work as well with OASIS due to differences in file transfer protocol implementation. Telix is best second choice, followed by Hyperterm.