7.2.3.13 Fill Option

The -fill option is used for filling unused (unspecified) memory locations in a HEX file with a known value.

The usage of this option is:
-fill=[wwidth:]fill_expr@address[:end_address]
where the arguments have the following meaning:
wwidth
signifies the decimal width of each constant in the fill_expr and can range from 1 thru 9. If this width is not specified, the default value is two bytes. For example, -fill=w1:0x55@0:0xF with fill every unused byte between address 0 and 0xF with the byte value 0x55, for example:
:10000000FBEF3FF0555555555555555555555555DB
whereas -fill=w2:0x55@0:0xF with fill every unused byte between the same addresses with the value 0x0055, for example:
:10000000FBEF3FF0550055005500550055005500D9
fill_expr
defines the values to fill and consists of const, which is a base value to place in the first memory location and optionally with increment, which indicates how this base value should change after each use. If the base value specifies more than one byte, these are stored in little-endian byte order. These following show the possible fill expressions:
  • const fill memory with a repeating constant; i.e., -fill=0xBEEF@0:0x1FF fills unused locations starting at address 0 with the values 0xBEEF, 0xBEEF, 0xBEEF, 0xBEEF, etc., for example:
    :10000000FBEF3FF0EFBEEFBEEFBEEFBEEFBEEFBEC9
  • const+=increment fill memory with an incrementing constant; i.e., -fill=0xBEEF+=1@0:0x1FF attempts to fills with the values 0xBEEF, 0xBEF0, 0xBEF1, 0xBEF2, etc., for example:
    :10000000FBEF3FF0F1BEF2BEF3BEF4BEF5BEF6BEAE
    Note that const increments with each location scanned, regardless of whether that location is populated or unused.
  • const-=increment fill memory with a decrementing constant; i.e.,-fill=0xBEEF-=0x10@0:0x1FF attempts to fills with the values 0xBEEF, 0xBEDF, 0xBECF, 0xBEBF, etc., for example:
    :10000000FBEF3FF0CFBEBFBEAFBE9FBE8FBE7FBE79
    Note that const decrements with each location scanned, regardless of whether that location is populated or unused.
  • const,const,...,const fill memory with a list of repeating constants; i.e., -fill=0xDEAD,0xBEEF@0:0x1FF fills with 0xDEAD, 0xBEEF, 0xDEAD, 0xBEEF, etc., for example:
    :10000000FBEF3FF0ADDEEFBEADDEEFBEADDEEFBE2F
@address
fills a specific address with fill_expr. The interpretation of this address is based on the addressing value. For example, -fill=0xBEEF@0x1000 puts the byte value 0xEF at addresses 0x1000 when the addressing value is set to 1.
:01100000EF00
If the -addressing=2 option had been additionally used in the above example, the fill option would place 2-bytes at address 0x2000 and 0x2001.
:02200000EFBE31
:end_address
optionally specifies an end address to be filled with fill_expr. The interpretation of this address is based on the addressing value. For example, -fill=0xBEEF@0xF0:0xFF puts 0xBEEF in unused addresses between 0 and 0xFF, inclusive.
:1000F000EFBEEFBEEFBEEFBEEFBEEFBEEFBEEFBE98
If the address range (multiplied by the addressing value) is not a multiple of the fill value width, the final location will only use part of the fill value, and a warning will be issued.

For Baseline and Mid-range PIC devices, as well as all 24-bit PIC and DSC devices, you can, if desired, specify a value of 2 with Hexmate's -addressing option so that the addresses used in this option will be device addresses. For all other devices, use the default addressing value or specify an addressing value of 1.

The fill values are word-aligned so they start on an address that is a multiple of the fill width. Should the fill value be an instruction opcode, this alignment ensures that the instruction can be executed correctly. Similarly, if the total length of the fill sequence is larger than 1 (and even if the specified width is 1), the fill sequence is aligned to that total length. For example the following fill option, which specifies 2 bytes of fill sequence and a starting address that is not a multiple of 2:
-fill=w1:0x11,0x22@0x11001:0x1100c
will result in the following HEX record, where the starting address was filled with the second byte of the fill sequence due to this alignment.
:0C100100221122112211221122112211B1
Compare that to when the option is -fill=w1:0x11,0x22@0x11000:0x1100c, which does specify a starting address that is a multiple of 2.
:0D10000011221122112211221122112211A0

All fill constants (excluding the width specification) can be expressed in (unsigned) binary, octal, decimal or hexadecimal, as per normal C syntax, for example, 1234 is a decimal value, 0xFF00 is hexadecimal and FF00 is illegal.