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 a post-build step in the IDE, Hexmate will not find a hex file with which to work. This behavior 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:

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 will only read and process the data from address 0 to 0x5ff in the final.hex file.

Also, there are some general options.

Hexmate has online 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. This 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 the Hexmate options relate to addresses in the HEX file. Unfortunately, the program memory of some Microchip PIC^® devices is 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:

If you are merging HEX files and you receive an error similar to:

This means that more than one HEX file has data at the address indicated and the resulting conflict has prevented a merger. 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 several 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 these steps:

• 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.

Hexmate 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:

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 that 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.

So the full command might look something like this:

If you receive the error:

It 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.