nshex - diff

The diff command creates a differential HEX image using two other images. The most common usage is to create a differential update file for your bootloader.

This command requires two images. The Reference image represent an image that may have been programmed on the device already. The Source image represents a new image, which you want to be programmed on the device.

nshex scans the Source image and compares it to the Reference image. Every part of the Source image which is present in the Reference image and has the same contents as the corresponding part in the Reference image gets removed. What remained of the Source image after all removals is stored as the Target image.

 

Syntax

target = diff(reference,source,units)

Argument	Description
reference	The Reference image.
source	The Source image.
units	Optional. Comarison units. May be one of the following: word - The unit of comparison is the instruction word. The comparison is made instruction by instruction. This option removes the most, but may cause fragmentation of the HEX file, and it may even become bigger than the Source image. row - Default. The unit of comarison is the flash row. Rows are going to be removed only if the whole row in the Source image is identical to the corresponding row in the Reference image. However, if the Source image contains only a part of a row, such row will still be compared and may be removed. Rows only apply to code memory. Other types of memory (UID,OTP,EEPROM etc.) are still compared word by word. The configuration bits are compared row by row if they are located within code memory. If configuration bits have a special location (such as on PIC16, PIC18 and some PIC24), they are compared word by word. page - The unit of comarison is the flash erase page. Pages are going to be removed only if the whole page in the Source image is identical to the corresponding page in the Reference image. However, if the Source image contains only a part of a page, such page will still be compared and may be removed. Pages only apply to code memory. Other types of memory (UID,OTP,EEPROM etc.) are still compared word by word. The configuration bits are compared page by page if they are located within code memory. If configuration bits have a special location (such as on PIC16, PIC18 and some PIC24), they are compared word by word.

 

Examples

diff_update = diff(version_3,version_4,page)

This command compares the version_4 HEX image to version_3 HEX image and removes all the pages which are the same. diff_update will consists of all the pages which are present in the version_4 image, but are either missing in the version_3 HEX file, or the page from version_4 is different from the page contained in version_3.

 

# update.txt - create differential update

#read the reference version HEX file
old = read(%1.hex)

#read the new version HEX file
new = read(%2.hex)
new = extract(new,code)

#create and save the update
old = expand(old,page)
new = expand(new,page)
update = diff(old,new,page)
write(update,%1_to_%2.hex)

This example shows an entire nshex command file which can be used to prepare a differential (incremental) update for a bootloader. It first reads two hex images from the hex files. The names of the files will be supplied in the command line. It also uses the extract command to make sure that the file doesn't contain configuration bits or any other unwanted memory. This is done because the bootloader can only write code memory.

Then both files get expanded to whole pages. The bootloader will erase pages, and we want to make sure it doesn't erase something important. The expand is used for this purpose.

Finally, the diff command is used to produce the differential update and save it. The resulting HEX file makes the bootloader job really easy - the HEX file contains only whole pages and the pages are sorted.

This command file could be used like this:

nshex -s update.txt -d dsPIC33EP256MU814 fwv3 fwv4

This would read the fwv4.hex and fwv3.hex files, produce the differential update and save it as fwv3_to_fwv4.hex file.