Hex Map Object

Hex Map object represents a map and content of the target device program memory. Hex Map objects are typically loaded from a HEX file for programming target device.

The Hex Map object consists of a number of blocks represented by Hex Block structures. Each Hex Block structure represents a continuous range of memory located at the specified address along with the contents of the memory.

Type

typedef struct hex_map *hex_map_t;

hex_map_t is an opaque reference to a Hex Map object. It is passed to all functions dealing with Hex Map objects.

Creation and Destruction

Typically, Hex Map Objects are created by loading a HEX file using hex_map_read or hex_map_read_fd functions.

It is also possible to create an empty Hex Map object with hex_map_alloc function, and then populate it with memory blocks.

Hex Map objects can also be created by copying existing Hex Map objects with hex_map_copy function, or by merging two Hex Map objects into one with hex_map_merge function.

When a Hex Map object is no longer needed, it must be freed using hex_map_free function.

Normalization

The blocks can be located within a Hex Map object in any order. The ranges of memory represented by blocks may overlap. This is Ok for some operations, such as programming the target device, but for most operations, the Hex Map object must be normalized - blocks must be sorted by the addresses, there must be no overlaps, adjacent ranges must be joined. This can be done using hex_map_normalize function.

Normalization will fail if there are overlapped ranges with different contents.

File Operations

Hex Map objects can be read from HEX files with hex_map_read or hex_map_read_fd functions.

Hex Map objects can be saved as HEX files with hex_map_write or hex_map_write_fd function.

Some of the HEX files may contain target device name. This is not a standard feature, but is supported by the library. The target device names are embedded after the end of the HEX file, for example:

:00000001FF
;dsPIC33CK1024MP708

The name of the device is stored within the Hex Map object and can be accessed with hex_map_get_device and hex_map_set_device functions.

Accessing and Modifying content

You can enumerate Hex blocks within the Hex Map object with hex_map_first_block and hex_block_next functions. These functions expose pointers to Hex Block structures within the Hex Map object. Hex Block structures can be modified directly.

The hex_map_append_block function appends a new Hex block at the end of the Hex Map object. The hex_map_delete_block function removes a Hex block from the Hex Map object.

The hex_map_partition function adds a special Hex blocks which contains configuration bits for the target device. These configuration bits will cause target device to be partitioned if the Hex Map object is programmed onto the device.