HI-TECH Software Forums: Intel HEX editing utility (v1.118)

Many thanks to all of the productive feedback during the Hexmate Beta Program.
Hexmate now continues to receive regular updates outside of this forum. If you are looking to obtain a copy of hexmate, it is now recommended that you obtain a more up-to-date version from within the compiler. If you don't have a compiler license, feel free to download our free PIC10/12/16, PIC18 or PIC32 compilers.

Formal and up-to-date documentation explaining hexmate's usage and options can be found in the Linker and Utilities chapter of the compiler's user manual. Although binary updates in this forum will become less frequent, bug reports and feature requests are still welcomed by emailing support@htsoft.com.
Thanks once again for your feedback and support of this utility.

The history of the Hexmate Beta Program will be retained and reads as follows:

In response to popular request by many customers, HI-TECH Software are presently developing a new utility to compliment all existing HI-TECH C compilers. Hexmate is a post-link stage utility that provide the facilty to:

Calculate and store checksum values
Fill unused memory locations with known data sequences
merge multiple Intel hex files with one output file
Convert INHX32 files to other INHX formats (eg. INHX8M)
Detect opcode sequences within a hexfile
Find/replace opcode sequences
Validate checksum integrity within hex files
Change or fix the length of INHX data records

It is expected that Hexmate will become an integrated component in all HI-TECH C compilers, but at this Beta stage it is provided as a free standalone command-line utility.

Note: from version 1.56 onward, hexmate will need access to a separate error messages file. The file en_msgs.txt is included in the attached .zip. Unless you have a hexmate-equipped version 9.xx HI-TECH compiler installed, en_msgs.txt should exist in the ./ directory. Ie. current working directory.

Typical applications for Hexmate might include:

merging a bootloader or debug module into a main application at build time

calculating a checksum over a range of program memory and storing its value in program memory or EEPROM

Filling unused memory locations with an instruction to send the PC to a known location if it gets lost.

Storage of a serial number at a fixed address.

Storage of a string (eg. time stamp) at a fixed address.

Store initial values at a particular memory address (eg. initialise EEPROM)

Detect usage of a buggy instruction (eg. LFSR in PIC18C452).

Fix the length of data records as required by some bootloaders.

Hexmate accepts the following command line parameters:
filename.hex List INHX32 input files to feed to hexmate. A range restriction can be applied by appending ,startAddress-endAddress. The data can be stored at an offset address by appending +offset.
eg. myfile.hex,0-1FF+1E00 will read in code from myfile.hex which falls within address range 0h - 1FFh (inclusive), but write this code to addresses 1E00h - 1FFFh.
CAUTION: Be careful when shifting sections of executable code. Program code shouldn't be shifted unless it can be guarenteed that no part of the program relies upon the absolute location of this code segment.

+ Prefix to an input file or command to force data storage. Overwrite other data if required.
eg. +input.hex +-STRING@1000="Forced"

-CK (calculate a checksum)
eg. -CK=0-1FFF@2FFE+2100w2 Calculate a checksum over the range 0-1FFFh and program the checksum result at address 2FFEh, checksum value will apply an initial offset of 2100h and the result will be 2 bytes wide. (Checksum offset is optional)(result width is optional, valid range = 1-4 bytes, default=2 bytes)

-FILL (fill unused memory locations with a known value)
eg. -FILL=446F@0-1FFF Will program hex op code 446Fh in all unused addresses from program memory address 0 to 1FFFh. -FILL accepts whole bytes of hex data from 1 to 8 bytes in length.

-FIND (Detect usage an opcode or partial code sequence)
eg. -FIND=010F@0-7FFF/2w Will detect the code sequence 010Fh when aligned on a /2 (two) byte boundary between 0h and 7FFFh. w indicates that a warning will be issued when this sequence is found, otherwize detections are saved to the nominated logfile.
eg. -FIND=010FMFFF0@0-7FFF/2wt"AddXY" is same as last example but the code sequence to match is masked with FFF0h, so HexMate will search for 010x. Messages/warnings will refer to this result by title "AddXY".
-FIND accepts whole bytes of hex data from 1 to 8 bytes in length.
-BREAK (Enforce a discontinuity in data records at this address)
eg. -BREAK=7FF8 will split a data record that covered a range which includes 7FF8h and recommence with a new data record at 7FF8h.
-FORMAT (Specify particular flavour of INHX, set max data record length)
eg. -FORMAT=INHX8M,16 will create the output in INHX8M with data records of max. length 16 byes.
Note: Currently INHX32(default) and INHX8M are the only supported output types. Data records must be a length between 1-16 bytes.

-HELP<=suboption> (List all hexmate options, or detailed help on specified sub-option)
eg. -HELP=string will show the usage of the -STRING option.

-LOGFILE (save hexfile statistics to a file)
eg. -LOGFILE=output.log will generate a report on the contents of the resultant hexfile and save it to file output.log.

-Ofile (Save output to the named file)
eg. -Oprogram.hex will save the resultant output to "program.hex"

-SERIAL (Store a particular hex value at a fixed address)
eg. -SERIAL=000001@EFFE will store hex code 00001h to address EFFEh.
Note: -SERIAL accepts optional parameters to customise storage of a series of codes. Enhanced usage is as follows
-SERIAL=CODE<+/-increment>@address<+/-interval><(r)repetitions>
eg. -SERIAL=0000+2@1000+10r5
Will store 5 codes, beginning with value 0000 at address 1000h. Subsequent codes will appear at address intervals of +10h and the code value will change in increments of +2.
-STRING (Embed a string at a fixed address)
eg. [Email]-STRING@1000="Some[/Email] string" will store the ASCII data for the string Some string (including null terminator) at address 1000h.
eg2. [Email]-STRING@1000t34="Some[/Email] string" will store the same string but every byte in the string will be trailed with the hexcode 34h. On a midrange PIC controller this will store the string in a series of RETLW instructions.

-SIZE (Report the number of bytes of data in this image)
The result is reported to STDOUT. If a log file is also produced, the size will be recorded here also.

,REPLACE (Used only with -FIND, replace the the found code sequence with this code sequence)
eg. -FIND=010FMFFF0@0-7FFF/2w,REPLACE=FFFF replaces word-aligned 010x sequence with FFFF.
The replace sequence can also be masked.
Note: Find/Replace code sequences must be of identical length.

-Wlevel(!) (Adjust warning sensitivity)
eg. -W5 will quieten all warnings with priority less than 5.
-W5! will do as above but terminate if any warnings are heard.

A typical usage of hexmate is as follows:
hexmate.exe bootldr.hex main.hex -Omainboot.hex -FILL=1234@0-FFFF +-CK=0-FFFF@200000w4tF0 -W3 -SERIAL=0001@E000

This command will merge bootldr.hex and main.hex into a common file named mainboot.hex.
All unused addresses between 0 and FFFFh will be filled with op code 1234h.
A checksum will be calculated over this range and it's 4-Byte result will be programmed into address 200000h (user ID area of PIC18). Because the the optional tF0 specifier was used, the upper byte of each register will contain the code F0h.
The checksum has permission to overwrite anything at its storage location because the -CK option was preceded with +.
All warnings less than priority level 3 will not be heard.
A fixed hex code (0001h) will be stored at address E000h. Note that address E000h is within the checksum range so this code will be incorporated in the checksum.

Multiple -CK specifications are allowed as are multiple -SERIAL specifications.

Feel free to download and experiment with the attached product. If you should notice any failures when using hexmate or have any suggestions on how we can improve this utility, please address an email to support@htsoft.com with the subject titled Hexmate beta.

The attached executable is provided as a Beta product. No warranty is provided and we accept no liability for any failures that may result.

Revision history
1.118 Added -FIND...,DELETE option
1.117 Added -SIZE option
1.116 Added -STRPACK option
1.115 Added -BREAK option
1.112-114 Internal HTSOFT changes
1.111 CRCs implemented in -CK option
1.110 Fix: Effect of -ADDRESSING not passed on to -FIND
1.109 Added -ADDRESSING to change input addressing mode.
1.108 Fix: -CK's trailing data (t) was incorrect if used with (g).
1.107 Allow -FILL to terminate early if it hits an address range limit.
1.106 Improved -HELP
1.105 Added ,data option to -FILL to to select to only fill existing data records.
1.104 Increased max length of data record to 128
1.103 Selection of up to 8 checksum algorithms
1.102 Additional specs for input file now presented BEFORE filename
1.101 Endianism selection for checksum result is now possible
1.100 Fix: premature 04 record produced in rare circumstances
1.99 Feature: -O (with no output file specified) will generate not output the resultant hex image to STDOUT nor to file.
1.98 Increased maximum data record length to 32
1.97 Fix: Checksum result was always zero for 32 bit calculations
1.96 Internal HTSOFT changes
1.95 Fix: Extended address record was sometimes generated prematurely.
1.94 Removed checking for .hex extension on input files.
1.93 All address/data specifications in options are now processed as hexadecimal.
1.92 Added new selection INHX032 to -FORMAT option. This dummy format is the same as INHX32 but with include an extended address record for address zero.
1.91 Fix: The w (warning) feature of -FIND only works if the t (title) feature was also specified. Now the two features operate independently.
1.90 Improved -FIND. The log report used to show the find pattern used and the addresses of each matching sequence. Now the actual matching code sequences will be displayed aswell. Also applies to REPLACE feature.
1.88-1.89 Internal changes for htsoft.
1.87 Fixed error in Mac version (only): Unnecessary EADDR records generated.
1.86 Supports msgdisable feature
1.85 Continued fixes to -FIND: Some optional parameters were unneccesarily dependant on one another.
1.84 Fixed crash in -FIND if some optional parameters were omitted.
1.83 Internal changes for htsoft.
1.82 Wrong error message would have displayed for out-of-memory condition.
1.81 Better auto-version identification
1.80 Enhanced -FORMAT to allow spec of maximum data record length.
1.79 Feature: Allowed a Title to be specified in -FIND option
Fix: -FIND used the mask value from its ,REPLACE counterpart if FIND was given no mask at all.
1.78 Hexmate will issue a warning whenever an input hex file has a checksum mismatch.
1.77 Fix: An upper-address record was not generated if the lowest byte of data was at an address greater than FFFF0000h.
Change: Increased the maximum number of input file arguments from 3 to 5.
1.76 Minor internal changes, invisible to outside world.
1.75 Feature: added ability to specify an address range restriction to an input hex file. Also allows specification of an address-shift for input.
1.74 Change: the bitmask specifier in the FIND/REPLACE option has changed from & to M due to & being a Linux special.
Fix: the T specifier to define trailing code in the -STRING option is now case insensitive.
Fix: the bitmask option for -FIND was reading the opcode as the bitmask.
1.70 Updated error messages that specify an overspecification of certain options.
1.69, 1.71-1.73 A change for benefit of compiler integration
1.68 Now more details are recorded in the logfile (if generated) recording specific occurances of find/replace op-codes.
Now the INHX8M format is fully supported and selectable with the option -FORMAT=INHX8M
1.67 Changes to improve overall messaging ability
1.66 Added a -FORMAT option to specify types of INTEL Hex output. By default we generate INHX32 but should also
allow for INHX8M, possibly consider INHX16 and INHX8S later.
1.65 Now some results of the -FIND/REPLACE are written to the logfile.
1.64 FIX: ,Replace option is now case insensitive
Change: better error messages during FIND/REPLACE stages.
1.63 Fix: corrected the -FILL option so the address specs are read in as hexadecimal rather than decimal
Fix: The help/usage messages being displayed were all out by one.
Feature: Find/replace is now starting to work
1.62 FIX: The code that was meant to test for the oversupply of -fill options was actually testing the number of checksum specs. Therefore it may have been possible to oversupply -fill.
FEATURE: early stages of -FIND,REPLACE option.
1.61 Correction to remove a warning when building.
1.60 Corrected an error message that didn't display a new-line character properly.
1.54-1.59 Preparations for integration with compiler.
1.53 Now will generate 04 record to initialize upper address with 0000. This is a requirement for some device programmers eg. MicroPro PIC.
1.50-1.52 Preparations for integration with compiler.
1.49 Fixed a problem where hexmate got into a loop if an input file ended without having read an END record.
1.48 Corrected checksum calculation - in some cases the first byte in the calculated range was not included in the summation.
1.47 Corrected a check for a premature end-of-file in input sources.
1.46 - Added argument prefix '+'. Prefixing '+' to an option or input file will force the storage of that data ie. Overwrite other data if necessary.
- -HELP suboptions now show an example of that option's usage
- Now data sources are allowed to store at the same address if the data value is identical.
- Fixed -STRING as it used to crash if the 't' specifier wasn't used but the ASCII string contained a lower case 't'.
- Improved readability of some error messages.
1.45 added the ability to specify a trailing hexcode to each byte in the stored data of -STRING and -CK options. This is required for EEPROM storage in midrange PIC devices. Other uses can be to turn the string data into a series of RETLW instructions or to add the suggested code F0h to the upper byte of a PIC's user ID registers.
1.44 Fixed it so that the output file is allowed to be one of the input files. This allows simple modifications to existing files.
1.43 Updated the -HELP table, to exclude -TOP but include -STRPACK
1.42 - Removed -TOP option. This was used to specify the upper bound of the -FILL range. Now this information MUST be provided in the -FILL option itself. The new usage for -FILL is as follows:
-FILL=hexcode@start-end eg. -FILL=FFFF@0-0x1FFF
- This change makes it possible to specify multiple -FILL options. This could be usefull if you wanted to do a fill in program memory AND a fill in EEPROM memory.
- Now checksum calculations give a warning about void addresses if a void address is confirmed, not just if a void location is possible (-FILL not specified)
- Improved some help and error messages.
1.41 Added an optional result width specifier to the -CK option. Follow the destination with a w character and the number of bytes to store for the result. Valid widths are 1-Byte through to 4-Bytes. The w specifier can be used in conjunction with the initial offset parameter. If no width is specified, the result width will default to 2 bytes.
1.40 - Removed the error when no input files are specified. This allows the creation of an intel hexfile that contains ONLY data requested from command line specifications. Eg. create a file that just contains EEPROM initialization data or just contains ASCII strings etc.
- Added copyright notice to -HELP and when no options are specifed.
1.39 The checksum accumulator now detects whether a range includes a checksum result that can't be resolved. eg. -CKSUM=0-200@100 won't know what value exists at 100.
1.38 improved -HELP system. Output is now clearer and more readable. The option's usage has been enhanced to provide help on specific sub-options eg. -HELP=STRING will display help information specific to the -STRING option.
1.37 - increased number of -CKSUM ranged from 2 to 3.
- fixed a problem where the output record was inserting extra FFFF bytes after the end of the record data.
- fixed a problem where data from the last few output records may dissappeared.
1.36 - improved quality of data saved in logfile
1.35 - increased max. -SERIAL options from 2 to 4
- fixed a problem where some void addresses were being programmed with value 00.
1.34 - Enhanced -SERIAL option to allow customization of a series of codes to be stored,
- Now used summative checksum calculation rather than negative.
- Added -LOGFILE option to allow file statistics to be saved.
1.33 Removed error checking on limitation that was previously removed ie. checksum destination can now be specified below the range of calculations.
1.32 Corrected the calculation of user-specified checksum.
1.31 Improved error messaging to identify sources involved when one address is asked two store two data values.
1.30 Added a -STRING option to store a string of ASCII characters (incl. null terminator) at a specified address.
1.29 Fixed problem with command options specifying addresses greater than FFFFFFh.
1.28 Removed limitation where checksum result must be stored after range.
Removed limitation that incoming hex records must be sorted by order of ascending address.
-HELP option will identify the current build revision

Edited by lucky (Wed Dec 10 2008 04:18 PM)



	You are not logged in. [Login]			Main Index \| Search \| Active Topics \| New user \| Who's Online \| FAQ