Using Hexmate on the Command Line

Hexmate is a utility application that can perform a variety of tasks on HEX files and is shipped with and executed by the MPLAB® XC8 compiler and the MPLAB X Integrated Development Environment (IDE). Since it is invoked automatically in many instances, you may never need to run Hexmate explicitly, but if you do, this article contains general advice on Hexmate's command line options.

The MPLAB X IDE automatically invokes Hexmate to fill unused memory locations when requested or to merge HEX files into your project code when these files have been added to the IDE’s Loadable folder. Similarly, the MPLAB XC8 compiler uses Hexmate to perform many tasks, such as reformatting the HEX file, filling unused locations, inserting serial numbers, or calculating and inserting hash (checksum or CRC) values. In these situations, you do not need to explicitly run Hexmate as the IDE and the compiler will run the application for you. If you wish to use some of the advanced features of Hexmate that cannot be accessed via compiler options, or you are not using the MPLAB XC8 compiler, or you are not using the MPLAB X IDE, then you can run Hexmate as described here.

First, note that Hexmate, as its name suggests, can only be used to process HEX files, in particular, the widely published Intel HEX file format. It cannot be used to process binary (bin) files or ELF files, for example. Note, also, that when you perform a debug build in the MPLAB X IDE, only a debug file (for example ELF or COFF file) is left behind after the build. This means that if you manually run Hexmate from a script or command, or from a post-build step in the IDE, Hexmate will not find a hex file with which to work. This behaviour does not affect any operation when Hexmate is invoked by the IDE or compiler during the build step, such as merging hex files or calculating a hash value in the case of MPLAB XC8. By contrast, production builds do not delete the HEX file after completion and Hexmate can always be executed as required.

Hexmate is located in and can be run from the MPLAB XC8 compiler’s bin directory. Alternately Hexmate is located in the IDE’s bin directory. (Mac OS X Users, you will need to right-click the mplab_ide.app icon in the Finder, select Show Package Contents, then navigate to the Content > Resources > mplab_ide > bin directory to browse this application in the Finder.)

Hexmate can be invoked with a command line that has the general format:

hexmate  options  inputFiles
The ordering of the files and options is not important, and options are not case sensitive, other than the names of any files when you are using a case-sensitive host operating system.

The inputFiles can be one or more HEX files. Typically you want to read all of the data in each HEX file, but hexmate can be asked to read only portions of the files by prefixing each filename with a read address specification, in the form rstart-end,filename. For example r0-5ff,final.hex, which will only read and process the data from address 0 to 0x5ff in the final.hex file.

There are some general options that you should be aware of.

Hexmate has on-line help. Use the -HELP option for the option details to be printed to the terminal output.

The -O option allows you to specify the output file name. If you do not specify a file, the output will be printed to the stdout stream.

An important option is the -ADDRESSING option which controls how addresses in the Hexmate command line are interpreted. The Intel HEX file uses byte addressing for the data it holds, which means that each byte of data in the file has an address one larger than the previous byte. This is important because all addresses specified in Hexmate options relate to addresses in the HEX file. Unfortunately, the program memory of some Microchip PIC devices are not byte addressed. The mid-range devices, for example, require two bytes of data to specify each program memory address, thus, address 0x0 in the device will be programmed by the two bytes at address 0x0 and 0x1 in the HEX file; address 0x1 in the device will be programmed by the bytes at address 0x2 and 0x3 in the HEX file, etc. Typically you want to be able to specify the device address when using Hexmate. So, for example, you might ask for a checksum to be placed at address 0x1000 with the intention that it will reside in the device’s memory space at address 0x1000, not 0x1000 in the hex file. For devices that do not have byte addressing, the -ADDRESSING option can be used to request that Hexmate interpret all option addresses as device addresses and map these to the appropriate HEX file addresses. For baseline, mid-range and all 24-bit devices, specify an addressing value of 2; for all other devices, use the default addressing value or specify an addressing value of 1.

The most common usage of Hexmate is to merge two or more HEX files into one. This might be useful if a bootloader and application are built separately. Assuming that you want to read all the data within each HEX file, the command to perform this might be as simple as the following:

hexmate  -Oproduct_v1_12.hex  bootloader.hex  application.hex
(You will need to specify the full location of Hexmate if it is not in your terminal's search path.) If you are merging hex files and you receive an error similar to:
(944) data conflict at address 828h between main.hex and main2.hex
this means that more than one HEX file has data at the address indicated and that this conflict has prevented merging. The address specified in the message will always be the address in the HEX files. Note that Hexmate will not produce an error if identical data is located at the same address in more than one file.

Another common Hexmate task is to calculate a hash value from a HEX file and insert that value into the file. Hexmate can execute a number of checksum or CRC hash algorithms. Further information about calculating hashes when using MPLAB XC8 is available in this article, but the same algorithms can be selected when running Hexmate explicitly.

If you intend to manually generate a hash using Hexmate, you will need to follow the steps listed here.

  • Reserve space for the hash value in the HEX file when you build using your compiler of choice
  • Fill unused program memory locations so that you get a consistent result from build to build
  • Calculate the hash using the desired algorithm and specification options to Hexmate

Hemate can perform the latter two of these steps.

To fill unused memory, use the -FILL option. Indicate the fill value and the address range over which to fill. Typically you would fill each unused bit with ‘1’ and you would cover the entire program memory range over which the hash is being calculated. So to fill any unused memory between address 0 and 0x7ff, for example, use the option:

-FILL=0xFF@0x0:0x7FF
If you specified an -ADDRESSING option with the value 2, then you might fill with 0x3FFF for a mid-range device or 0xFFFF for a 24-bit device, since each address specifies two bytes in the file.

The hash value can be calculated using the -CK option. Check the MPLAB XC8 User's Guide for more information on this option; however, here is an example of an option which calculates a CRC (g5), using an initial value of 0xFFFF and a polynomial value of 0x1021 (p1021) from the HEX file data at addresses 0 through to 0x7FF, placing the little-endian, 2-byte-wide result (w-2) at address 0x1000 in the final HEX file.

-CK=0x0-0x7FF@0x1000+FFFFw-2g5p1021
So the full command might look something like:
hexmate -FILL=0xFF@0x0:0x7FF -CK=0x0-0x7FF@0x1000+FFFFw-2g5p1021 -Ofinal.hex -LOGFILE=final.hxl project.hex
If you receive the error:
(944) data conflict at address 1000h between main.hex and Reserved for checksum
this means that there is data at the address where you have asked for the checksum to be positioned. Ensure that the location for the checksum has been reserved when you build your project. This step cannot be performed by Hexmate.

Note that in this example a log file was requested. The log file will confirm the addresses over which the hash was calculated and the final hash value. This is a useful file to generate whenever you run Hexmate.

For other Hexmate options, see the Utilities Chapter in the MPLAB XC8 C Compiler User’s Guide.

© 2016 Microchip Technology, Inc.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.