8.2.3.13 Fill Option

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

Note: If you are using the xc8-cc driver's command-line option to fill unused memory, the option is --fill (two leading dash characters). If you are calling the Hexmate utility directly, the option is -fill (one leading dash).

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 will fill every unused byte between address 0 and 0xF with the byte value 0x55, for example:

:10000000FBEF3FF0555555555555555555555555DB

whereas -fill=w2:0x55@0:0xF will 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, the bytes are stored in little-endian byte order. The following show the possible fill expressions:

const fill memory with a repeating constant; for example, -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; for example, -fill=0xBEEF+=1@0:0x1FF attempts to fill 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; for example,-fill=0xBEEF-=0x10@0:0x1FF attempts to fill 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; for example, -fill=0xDEAD,0xBEEF@0:0x1FF will fill 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.