Contents#

Overview#

docs
tests
package

Library to handle hexadecimal record files

Free software: BSD 2-Clause License

Introduction#

The purpose of this library is to provide simple but useful methods to load, edit, and save hexadecimal record files.

In the field of embedded systems, hexadecimal record files are the most common way to share binary data to be written to the target non-volatile memory, such as a EEPROM or microcontroller code flash. Such binary data can contain compiled executable code, configuration data, volatile memory dumps, etc.

The most common file formats for hexadecimal record files are Intel HEX (.hex) and Motorola S-record (.srec). Other common formats for binary data exchange for embedded systems include the Executable and Linkable Format (.elf), hex dumps (by hexdump or xxd), and raw binary files (.bin).

A good thing about hexadecimal record files is that they are almost de-facto, so every time a supplier has to give away its binary data it is either in HEX or SREC, although ELF is arguably the most common for debuggable executables.

A bad thing is that their support in embedded software toolsets is sometimes flawed or only one of the formats is supported, while the supplier provides its binary data in the other format.

Another feature is that binary data is split into text record lines (thus their name) protected by some kind of checksum. This is good for data exchange and line-by-line writing to the target memory (in the old days), but this makes in-place editing by humans rather tedious as data should be split, and the checksum and other metadata have to be updated.

All of the above led to the development of this library, which allows to, for example:

convert between hexadecimal record formats;
merge/patch multiple hexadecimal record files of different formats;
access every single record of a hexadecimal record file;
build records through handy methods;
edit sparse data in a virtual memory behaving like a bytearray;
extract or update only some parts of the binary data.

Documentation#

For the full documentation, please refer to:

https://hexrec.readthedocs.io/

Architecture#

Within the hexrec package itself are the symbols of the most commonly used classes and functions.

As the core of this library are record files, the hexrec.base is the first module a user should look up. It provides high-level functions to deal with record files, as well as classes holding record data.

The hexrec.base allows to load bytesparse virtual memories, which are as easy to use as the native bytearray, but with sparse data blocks.

The hexrec.utils module provides some miscellaneous utility stuff.

hexrec.xxd is an emulation of the xxd command line utility delivered by vim.

The package can also be run as a command line tool, by running the hexrec package itself (python -m hexrec), providing some record file utilities. You can also create your own standalone executable, or download a precompiled one from the pyinstaller folder.

The codebase is written in a simple fashion, to be easily readable and maintainable, following some naive pythonic K.I.S.S. approach by choice.

Examples#

To have a glimpse of the features provided by this library, some simple but common examples are shown in the following.

Convert format#

It happens that some software tool only supports some hexadecimal record file formats, or the format given to you is not handled properly, or simply you prefer a format against another (e.g. SREC has linear addressing, while HEX is in a segment:offset fashion).

In this example, a HEX file is converted to SREC.

from hexrec import convert

convert('data.hex', 'data.srec')

This can also be done by running hexrec as a command line tool:

$ hexrec convert data.hex data.srec

Alternatively, by executing the package itself:

$ python -m hexrec convert data.hex data.srec

Merge files#

It is very common that the board factory prefers to receive a single file to program the microcontroller, because a single file is simpler to manage for them, and might be faster for their workers or machine, where every second counts.

This example shows how to merge a bootloader, an executable, and some configuration data into a single file, in the order they are listed.

from hexrec import merge

in_paths = ['bootloader.hex', 'executable.mot', 'configuration.xtek']
out_path = 'merged.srec'
merge(in_paths, out_path)

Alternatively, these files can be merged via manual load:

from hexrec import load, SrecFile

in_paths = ['bootloader.hex', 'executable.mot', 'configuration.xtek']
in_files = [load(path) for path in in_paths]
out_file = SrecFile().merge(*in_files)
out_file.save('merged.srec')

This can also be accomplished by running the hexrec package itself as a command line tool:

$ hexrec merge bootloader.hex executable.mot configuration.xtek merged.srec

Dataset generator#

Let us suppose we are early in the development of the embedded system and we need to test the current executable with some data stored in EEPROM. We lack the software tool to generate such data, and even worse we need to test 100 configurations. For the sake of simplicity, the data structure consists of 4096 random values (0 to 1) of float type, stored in little-endian at the address 0xDA7A0000.

import struct, random
from hexrec import SrecFile

for index in range(100):
    values = [random.random() for _ in range(4096)]
    data = struct.pack('<4096f', *values)
    file = SrecFile.from_bytes(data, offset=0xDA7A0000)
    file.save(f'dataset_{index:02d}.mot')

Write a CRC#

Usually, the executable or the configuration data of an embedded system are protected by a CRC, so that their integrity can be self-checked.

Let us suppose that for some reason the compiler does not calculate such CRC the expected way, and we prefer to do it with a script.

This example shows how to load a HEX file, compute a CRC32 from the address 0x1000 to 0x3FFB (0x3FFC exclusive), and write the calculated CRC to 0x3FFC in big-endian as a SREC file. The rest of the data is left untouched.

import binascii, struct
from hexrec import load

file = load('checkme.srec')

with file.view(0x1000, 0x3FFC) as view:
    crc = binascii.crc32(view) & 0xFFFFFFFF  # remove sign

file.write(0x3FFC, struct.pack('>L', crc))
file.save('checkme_crc.srec')

Trim for bootloader#

When using a bootloader, it is very important that the application being written does not overlap with the bootloader. Sometimes the compiler still generates stuff like a default interrupt table which should reside in the bootloader, and we need to get rid of it, as well as everything outside the address range allocated for the application itself.

This example shows how to trim the application executable record file to the allocated address range 0x8000-0x1FFFF. Being written to a flash memory, unused memory byte cells default to 0xFF.

from hexrec import load, SrecFile

in_file = load('application.mot')
data = in_file.read(0x8000, 0x1FFFF+1, fill=0xFF)

out_file = SrecFile.from_bytes(data, offset=0x8000)
out_file.save('app_trimmed.mot')

This can also be done by running the hexrec package as a command line tool:

$ hexrec crop -s 0x8000 -e 0x20000 -v 0xFF app_original.hex app_trimmed.srec

By contrast, we need to fill the application range within the bootloader image with 0xFF, so that no existing application will be available again. Also, we need to preserve the address range 0x3F800-0x3FFFF because it already contains some important data.

from hexrec import load

file = load('bootloader.hex')
file.fill(0x8000, 0x1FFFF+1, 0xFF)
file.clear(0x3F800, 0x3FFFF+1)
file.save('boot_fixed.hex')

With the command line interface, it can be done via a two-pass processing, first to fill the application range, then to clear the reserved range. Please note that the first command is chained to the second one via standard output/input buffering (the virtual - file path, in ihex format as per boot_original.hex).

$ hexrec fill -s 0x8000 -e 0x20000 -v 0xFF boot_original.hex - | \
  hexrec clear -s 0x3F800 -e 0x40000 -i ihex - boot_fixed.srec

(newline continuation is backslash \ for a Unix-like shell, caret ^ for a DOS prompt).

Export ELF sections#

The following example shows how to export sections stored within an Executable and Linkable File (ELF), compiled for a microcontroller. As per the previous example, only data within the range 0x8000-0x1FFFF are kept, with the rest of the memory filled with the 0xFF value.

from hexrec import SrecFile
from bytesparse import Memory
from elftools.elf.elffile import ELFFile  # "pyelftools" package

with open('appelf.elf', 'rb') as elf_stream:
    elf_file = ELFFile(elf_stream)

    memory = Memory(start=0x8000, endex=0x1FFFF+1)  # bounds set
    memory.fill(pattern=0xFF)  # between bounds

    for section in elf_file.iter_sections():
        if (section.header.sh_flags & 3) == 3:  # SHF_WRITE | SHF_ALLOC
            address = section.header.sh_addr
            data = section.data()
            memory.write(address, data)

out_file = SrecFile.from_memory(memory, header=b'Source: appelf.elf\0')
out_file.save('appelf.srec')

Installation#

From PyPI (might not be the latest version found on github):

$ pip install hexrec

From the source code root directory:

$ pip install .

Development#

To run the all the tests:

$ pip install tox
$ tox

Installation#

From PyPI#

At the command line:

$ pip install hexrec

The package found on PyPI might be outdated with respect to the source repository.

From source#

At the command line, at the root of the source directory:

$ pip install .

Command Line Interface#

hexrec#

A set of command line utilities for common operations with record files.

Being built with Click, all the commands follow POSIX-like syntax rules, as well as reserving the virtual file path - for command chaining via standard output/input buffering.

hexrec [OPTIONS] COMMAND [ARGS]...

align#

Pads blocks to align their boundaries.

INFILE is the path of the input file. Set to - to read from standard input; input format required.

OUTFILE is the path of the output file. Set to - to write to standard output. Leave empty to overwrite INFILE.

hexrec align [OPTIONS] [INFILE] [OUTFILE]

Options

-i, --input-format <input_format>#

Forces the input file format. Required for the standard input.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-o, --output-format <output_format>#

Forces the output file format. By default it is that of the input file.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-m, --modulo <modulo>#

Alignment modulo.

Default:: 4

-s, --start <start>#: Inclusive start address. Negative values are referred to the end of the data. By default it applies from the start of the data contents.

-e, --endex <endex>#: Exclusive end address. Negative values are referred to the end of the data. By default it applies till the end of the data contents.

-v, --value <value>#

Byte value used to flood alignment padding.

Default:: 0

-w, --width <width>#: Sets the length of the record data field, in bytes. By default it is that of the input file.

Arguments

INFILE#: Optional argument

OUTFILE#: Optional argument

clear#

Clears an address range.

INFILE is the path of the input file. Set to - to read from standard input; input format required.

OUTFILE is the path of the output file. Set to - to write to standard output. Leave empty to overwrite INFILE.

hexrec clear [OPTIONS] [INFILE] [OUTFILE]

Options

-i, --input-format <input_format>#

Forces the input file format. Required for the standard input.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-o, --output-format <output_format>#

Forces the output file format. By default it is that of the input file.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-s, --start <start>#: Inclusive start address. Negative values are referred to the end of the data. By default it applies from the start of the data contents.

-e, --endex <endex>#: Exclusive end address. Negative values are referred to the end of the data. By default it applies till the end of the data contents.

-w, --width <width>#: Sets the length of the record data field, in bytes. By default it is that of the input file.

Arguments

INFILE#: Optional argument

OUTFILE#: Optional argument

convert#

Converts a file to another format.

INFILE is the list of paths of the input files. Set to - to read from standard input; input format required.

OUTFILE is the path of the output file. Set to - to write to standard output. Leave empty to overwrite INFILE.

hexrec convert [OPTIONS] [INFILE] [OUTFILE]

Options

-i, --input-format <input_format>#

Forces the input file format. Required for the standard input.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-o, --output-format <output_format>#

Forces the output file format. By default it is that of the input file.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-w, --width <width>#: Sets the length of the record data field, in bytes. By default it is that of the input file.

Arguments

INFILE#: Optional argument

OUTFILE#: Optional argument

crop#

Selects data from an address range.

INFILE is the path of the input file. Set to - to read from standard input; input format required.

OUTFILE is the path of the output file. Set to - to write to standard output. Leave empty to overwrite INFILE.

hexrec crop [OPTIONS] [INFILE] [OUTFILE]

Options

-i, --input-format <input_format>#

Forces the input file format. Required for the standard input.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-o, --output-format <output_format>#

Forces the output file format. By default it is that of the input file.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-s, --start <start>#: Inclusive start address. Negative values are referred to the end of the data. By default it applies from the start of the data contents.

-e, --endex <endex>#: Exclusive end address. Negative values are referred to the end of the data. By default it applies till the end of the data contents.

-v, --value <value>#: Byte value used to flood the address range. By default, no flood is performed.

-w, --width <width>#: Sets the length of the record data field, in bytes. By default it is that of the input file.

Arguments

INFILE#: Optional argument

OUTFILE#: Optional argument

delete#

Deletes an address range.

INFILE is the path of the input file. Set to - to read from standard input; input format required.

OUTFILE is the path of the output file. Set to - to write to standard output. Leave empty to overwrite INFILE.

hexrec delete [OPTIONS] [INFILE] [OUTFILE]

Options

-i, --input-format <input_format>#

Forces the input file format. Required for the standard input.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-o, --output-format <output_format>#

Forces the output file format. By default it is that of the input file.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-s, --start <start>#: Inclusive start address. Negative values are referred to the end of the data. By default it applies from the start of the data contents.

-e, --endex <endex>#: Exclusive end address. Negative values are referred to the end of the data. By default it applies till the end of the data contents.

-w, --width <width>#: Sets the length of the record data field, in bytes. By default it is that of the input file.

Arguments

INFILE#: Optional argument

OUTFILE#: Optional argument

fill#

Fills an address range with a byte value.

INFILE is the path of the input file. Set to - to read from standard input; input format required.

OUTFILE is the path of the output file. Set to - to write to standard output. Leave empty to overwrite INFILE.

hexrec fill [OPTIONS] [INFILE] [OUTFILE]

Options

-i, --input-format <input_format>#

Forces the input file format. Required for the standard input.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-o, --output-format <output_format>#

Forces the output file format. By default it is that of the input file.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-v, --value <value>#

Byte value used to fill the address range.

Default:: 0

-s, --start <start>#: Inclusive start address. Negative values are referred to the end of the data. By default it applies from the start of the data contents.

-e, --endex <endex>#: Exclusive end address. Negative values are referred to the end of the data. By default it applies till the end of the data contents.

-w, --width <width>#: Sets the length of the record data field, in bytes. By default it is that of the input file.

Arguments

INFILE#: Optional argument

OUTFILE#: Optional argument

flood#

Fills emptiness of an address range with a byte value.

INFILE is the path of the input file. Set to - to read from standard input; input format required.

OUTFILE is the path of the output file. Set to - to write to standard output. Leave empty to overwrite INFILE.

hexrec flood [OPTIONS] [INFILE] [OUTFILE]

Options

-i, --input-format <input_format>#

Forces the input file format. Required for the standard input.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-o, --output-format <output_format>#

Forces the output file format. By default it is that of the input file.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-v, --value <value>#

Byte value used to flood the address range.

Default:: 0

-s, --start <start>#: Inclusive start address. Negative values are referred to the end of the data. By default it applies from the start of the data contents.

-e, --endex <endex>#: Exclusive end address. Negative values are referred to the end of the data. By default it applies till the end of the data contents.

-w, --width <width>#: Sets the length of the record data field, in bytes. By default it is that of the input file.

Arguments

INFILE#: Optional argument

OUTFILE#: Optional argument

hd#

Display file contents in hexadecimal, decimal, octal, or ascii.

The hexdump utility is a filter which displays the specified files, or standard input if no files are specified, in a user-specified format.

Below, the length and offset arguments may be followed by the multiplicative suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the “iB” is optional, e.g., “K” has the same meaning as “KiB”), or the suffixes KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.

For each input file, hexdump sequentially copies the input to standard output, transforming the data according to the format strings specified by the -e and -f options, in the order that they were specified.

hexrec hd [OPTIONS] [INFILE]

Options

-b, --one-byte-octal#: One-byte octal display. Display the input offset in hexadecimal, followed by sixteen space-separated, three-column, zero-filled bytes of input data, in octal, per line.

-X, --one-byte-hex#: One-byte hexadecimal display. Display the input offset in hexadecimal, followed by sixteen space-separated, two-column, zero-filled bytes of input data, in hexadecimal, per line.

-c, --one-byte-char#: One-byte character display. Display the input offset in hexadecimal, followed by sixteen space-separated, three-column, space-filled characters of input data per line.

-d, --two-bytes-decimal#: Two-byte decimal display. Display the input offset in hexadecimal, followed by eight space-separated, five-column, zero-filled, two-byte units of input data, in unsigned decimal, per line.

-o, --two-bytes-octal#: Two-byte octal display. Display the input offset in hexadecimal, followed by eight space-separated, six-column, zero-filled, two-byte quantities of input data, in octal, per line.

-x, --two-bytes-hex#: Two-byte hexadecimal display. Display the input offset in hexadecimal, followed by eight space-separated, four-column, zero-filled, two-byte quantities of input data, in hexadecimal, per line.

-n, --length <length>#: Interpret only length bytes of input.

-s, --skip <skip>#: Skip offset bytes from the beginning of the input.

-v, --no_squeezing#: The -v option causes hexdump to display all input data. Without the -v option, any number of groups of output lines which would be identical to the immediately preceding group of output lines (except for the input offsets), are replaced with a line comprised of a single asterisk.

-U, --upper#: Uses upper case hex letters on address and data.

-I, --input-format <input_format>#

Forces the input file format.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-V, --version#: Print version and exit.

Arguments

INFILE#: Optional argument

hexdump#

Display file contents in hexadecimal, decimal, octal, or ascii.

The hexdump utility is a filter which displays the specified files, or standard input if no files are specified, in a user-specified format.

hexrec hexdump [OPTIONS] [INFILE]

Options

-b, --one-byte-octal#: One-byte octal display. Display the input offset in hexadecimal, followed by sixteen space-separated, three-column, zero-filled bytes of input data, in octal, per line.

-X, --one-byte-hex#: One-byte hexadecimal display. Display the input offset in hexadecimal, followed by sixteen space-separated, two-column, zero-filled bytes of input data, in hexadecimal, per line.

-c, --one-byte-char#: One-byte character display. Display the input offset in hexadecimal, followed by sixteen space-separated, three-column, space-filled characters of input data per line.

-C, --canonical#: Canonical hex+ASCII display. Display the input offset in hexadecimal, followed by sixteen space-separated, two-column, hexadecimal bytes, followed by the same sixteen bytes in %_p format enclosed in | characters. Invoking the program as hd implies this option.

-d, --two-bytes-decimal#: Two-byte decimal display. Display the input offset in hexadecimal, followed by eight space-separated, five-column, zero-filled, two-byte units of input data, in unsigned decimal, per line.

-o, --two-bytes-octal#: Two-byte octal display. Display the input offset in hexadecimal, followed by eight space-separated, six-column, zero-filled, two-byte quantities of input data, in octal, per line.

-x, --two-bytes-hex#: Two-byte hexadecimal display. Display the input offset in hexadecimal, followed by eight space-separated, four-column, zero-filled, two-byte quantities of input data, in hexadecimal, per line.

-n, --length <length>#: Interpret only length bytes of input.

-s, --skip <skip>#: Skip offset bytes from the beginning of the input.

-v, --no_squeezing#: The -v option causes hexdump to display all input data. Without the -v option, any number of groups of output lines which would be identical to the immediately preceding group of output lines (except for the input offsets), are replaced with a line comprised of a single asterisk.

-U, --upper#: Uses upper case hex letters on address and data.

-I, --input-format <input_format>#

Forces the input file format.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-V, --version#: Print version and exit.

Arguments

INFILE#: Optional argument

merge#

Merges multiple files.

INFILES is the list of paths of the input files. Set any to - or none to read from standard input; input format required.

OUTFILE is the path of the output file. Set to - to write to standard output.

Every file of INFILES will overwrite data of previous files of the list where addresses overlap.

hexrec merge [OPTIONS] [INFILES]... OUTFILE

Options

-i, --input-format <input_format>#

Forces the input file format for all input files. Required for the standard input.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-o, --output-format <output_format>#

Forces the output file format. By default it is that of the input file.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-w, --width <width>#: Sets the length of the record data field, in bytes. By default it is that of the input file.

--clear-holes#: Merges memory holes, clearing data at their place.

Arguments

INFILES#: Optional argument(s)

OUTFILE#: Required argument

shift#

Shifts data addresses.

INFILE is the path of the input file. Set to - to read from standard input; input format required.

OUTFILE is the path of the output file. Set to - to write to standard output. Leave empty to overwrite INFILE.

hexrec shift [OPTIONS] [INFILE] [OUTFILE]

Options

-i, --input-format <input_format>#

Forces the input file format. Required for the standard input.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-o, --output-format <output_format>#

Forces the output file format. By default it is that of the input file.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-n, --amount <amount>#: Address shift to apply.

-w, --width <width>#: Sets the length of the record data field, in bytes. By default it is that of the input file.

Arguments

INFILE#: Optional argument

OUTFILE#: Optional argument

srec#

Motorola SREC specific

hexrec srec [OPTIONS] COMMAND [ARGS]...

del-header#

Deletes the header data record.

The header record is expected to be the first. All other records are kept as-is. No file-wise validation occurs.

INFILE is the path of the input file; ‘srec’ record type. Set to - to read from standard input.

OUTFILE is the path of the output file. Set to - to write to standard output. Leave empty to overwrite INFILE.

hexrec srec del-header [OPTIONS] [INFILE] [OUTFILE]

Arguments

INFILE#: Optional argument

OUTFILE#: Optional argument

get-header#

Gets the header data.

INFILE is the path of the input file; ‘srec’ record type. Set to - to read from standard input.

hexrec srec get-header [OPTIONS] [INFILE]

Options

-f, --format <format>#

Header data format.

Default:: ascii
Options:: ascii | hex | HEX | hex. | HEX. | hex- | HEX- | hex: | HEX: | hex_ | HEX_ | hex | HEX

Arguments

INFILE#: Optional argument

set-header#

Sets the header data record.

The header record is expected to be the first. All other records are kept as-is. No file-wise validation occurs.

INFILE is the path of the input file; ‘srec’ record type. Set to - to read from standard input.

OUTFILE is the path of the output file. Set to - to write to standard output. Leave empty to overwrite INFILE.

hexrec srec set-header [OPTIONS] HEADER [INFILE] [OUTFILE]

Options

-f, --format <format>#

Header data format.

Default:: ascii
Options:: ascii | hex | HEX | hex. | HEX. | hex- | HEX- | hex: | HEX: | hex_ | HEX_ | hex | HEX

Arguments

HEADER#: Required argument

INFILE#: Optional argument

OUTFILE#: Optional argument

validate#

Validates a record file.

INFILE is the path of the input file. Set to - to read from standard input; input format required.

hexrec validate [OPTIONS] [INFILE]

Options

-i, --input-format <input_format>#

Forces the input file format. Required for the standard input.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

Arguments

INFILE#: Optional argument

xxd#

Emulates the xxd command.

Please refer to the xxd manual page to know its features and caveats.

Some parameters were changed to satisfy the POSIX-like command line parser.

hexrec xxd [OPTIONS] [INFILE] [OUTFILE]

Options

-a, --autoskip#

Toggles autoskip.

A single ‘*’ replaces null lines.

-b, --bits#

Binary digits.

Switches to bits (binary digits) dump, rather than hexdump. This option writes octets as eight digits of ‘1’ and ‘0’ instead of a normal hexadecimal dump. Each line is preceded by a line number in hexadecimal and followed by an ASCII (or EBCDIC) representation. The argument switches -r, -p, -i do not work with this mode.

-c, --cols <cols>#

Formats <cols> octets per line. Max 256.

Defaults: normal 16, -i 12, -p 30, -b 6.

-E, --ebcdic, --EBCDIC#

Uses EBCDIC charset.

Changes the character encoding in the right-hand column from ASCII to EBCDIC. This does not change the hexadecimal representation. The option is meaningless in combinations with -r, -p or -i.

-e, --endian#

Switches to little-endian hexdump.

This option treats byte groups as words in little-endian byte order. The default grouping of 4 bytes may be changed using -g. This option only applies to hexdump, leaving the ASCII (or EBCDIC) representation unchanged. The switches -r, -p, -i do not work with this mode.

-g, --groupsize <groupsize>#

Byte group size.

Separates the output of every <groupsize> bytes (two hex characters or eight bit-digits each) by a whitespace. Specify <groupsize> 0 to suppress grouping. <groupsize> defaults to 2 in normal mode, 4 in little-endian mode and 1 in bits mode. Grouping does not apply to -p or -i.

-i, --include#

Output in C include file style.

A complete static array definition is written (named after the input file), unless reading from standard input.

-l, --length, --len <length>#: Stops after writing <length> octets.

-o, --offset <offset>#: Adds <offset> to the displayed file position.

-p, --postscript, --plain, --ps#

Outputs in postscript continuous hexdump style.

Also known as plain hexdump style.

-q, --quadword#: Uses 64-bit addressing.

-r, --revert#

Reverse operation.

Convert (or patch) hexdump into binary. If not writing to standard output, it writes into its output file without truncating it. Use the combination -r and -p to read plain hexadecimal dumps without line number information and without a particular column layout. Additional Whitespace and line breaks are allowed anywhere.

-k, --seek <oseek>#

Output seeking.

When used after -r reverts with -o added to file positions found in hexdump.

-s <iseek>#

Input seeking.

Starts at <s> bytes absolute (or relative) input offset. Without -s option, it starts at the current file position. The prefix is used to compute the offset. ‘+’ indicates that the seek is relative to the current input position. ‘-’ indicates that the seek should be that many characters from the end of the input. ‘+-’ indicates that the seek should be that many characters before the current stdin file position.

-U, --upper-all#: Uses upper case hex letters on address and data.

-u, --upper#: Uses upper case hex letters on data only.

-I, --input-format <input_format>#

Forces the input file format.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

-O, --output-format <output_format>#

Forces the output file format.

Options:: asciihex | avr | ihex | mos | raw | srec | titxt | xtek

--seek-zeroes, --no-seek-zeroes#

Output seeking writes zeroes while seeking.

Default:: True

-v, --version#: Prints the package version number.

Arguments

INFILE#: Optional argument

OUTFILE#: Optional argument

Reference#

`hexrec.base`	Base types and classes.
`hexrec.formats`	Record formats.
`hexrec.formats.asciihex`	ASCII-hex format.
`hexrec.formats.avr`	Atmel Generic format.
`hexrec.formats.ihex`	Intel HEX format.
`hexrec.formats.mos`	MOS Technology format.
`hexrec.formats.raw`	Binary format.
`hexrec.formats.sqtp`	Microchip Serial Quick Time Programming format.
`hexrec.formats.srec`	Motorola S-record format.
`hexrec.formats.titxt`	Texas Instruments TI-TXT format.
`hexrec.formats.xtek`	Tektronix extended HEX format.
`hexrec.hexdump`	Emulation of the hexdump utility.
`hexrec.utils`	Generic utility functions.
`hexrec.xxd`	Emulation of the xxd utility.

Contributing#

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Bug reports#

When reporting a bug please include:

Your operating system name and version.

Any details about your local setup that might be helpful in troubleshooting.

Detailed steps to reproduce the bug.

Documentation improvements#

hexrec could always use more documentation, whether as part of the official hexrec docs, in docstrings, or even on the web in blog posts, articles, and such.

Feature requests and feedback#

The best way to send feedback is to file an issue at https://github.com/TexZK/hexrec/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that code contributions are welcome :)

Development#

To set up hexrec for local development:

Fork hexrec (look for the “Fork” button).

Clone your fork locally:

git clone git@github.com:your_name_here/hexrec.git

Create a branch for local development:
```
git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.
When you’re done making changes, run all the checks, doc builder and spell checker with tox one command:
```
tox
```

Commit your changes and push your branch to GitHub:

git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Pull Request Guidelines#

If you need some code review or feedback while you’re developing the code just make the pull request.

For merging, you should:

Include passing tests (run tox).
Update documentation when there’s new API, functionality etc.
Add a note to CHANGELOG.rst about the changes.
Add yourself to AUTHORS.rst.

Tips#

To run a subset of tests:

tox -e envname -- pytest -k test_myfeature

To run all the test environments in parallel (you need to pip install detox):

detox

Authors#

Andrea Zoppi - main developer - https://github.com/TexZK

Special thanks#

Scott Finneran - main developer of the SRecord project - https://srecord.sourceforge.net/

Changelog#

0.4.0 (TBD)#

Library rewritten from scratch (not backwards compatible).
Added new object oriented API, hopefully more user friendly.
Added Texas Instruments TI-TXT file format.
Improved docs and examples.

0.3.1 (2024-01-23)#

Added support for Python 3.12.
Added Motorola header editing.
Minor fixes and changes.

0.3.0 (2023-02-21)#

Added support for Python 3.11, removed 3.6.
Deprecated hexrec.blocks module entirely.
Using bytesparse for virtual memory management.
Improved repository layout.
Improved testing and packaging workflow.
Minor fixes and changes.

0.2.3 (2021-12-30)#

Removed dependency of legacy pathlib package; using Python’s own module instead.
Added support for Python 3.10.
Fixed maximum SREC length.
Changed pattern offset behavior.
Some alignment to the bytesparse.Memory API; deprecated code marked as such.

0.2.2 (2020-11-08)#

Added workaround to register default record types.
Added support for Python 3.9.
Fixed insertion bug.
Added empty space reservation.

0.2.1 (2020-03-05)#

Fixed flood with empty span.

0.2.0 (2020-02-01)#

Added support for current Python versions (3.8, PyPy 3).
Removed support for old Python versions (< 3.6, PyPy 2).
Major refactoring to allow an easier integration of new record formats.

0.1.0 (2019-08-13)#

Added support for Python 3.7.

0.0.4 (2018-12-22)#

New command line interface made with Click.
More testing and fixing.
Some refactoring.
More documentation.

0.0.3 (2018-12-04)#

Much testing and fixing.
Some refactoring.
More documentation.

0.0.2 (2018-08-29)#

Major refactoring.
Added most of the documentation.
Added first drafts to manage blocks of data.
Added first test suites.

0.0.1 (2018-06-27)#

First release on PyPI.
Added first drafts to manage record files.
Added first emulation of xxd.

Contents#

Overview#

Introduction#

Documentation#

Architecture#

Examples#

Convert format#

Merge files#

Dataset generator#

Write a CRC#

Trim for bootloader#

Export ELF sections#

Installation#

Development#

Installation#

From PyPI#

From source#

Command Line Interface#

hexrec#

align#

clear#

convert#

crop#

delete#

fill#

flood#

hd#

hexdump#

merge#

shift#

srec#

del-header#

get-header#

set-header#

validate#

xxd#

Reference#

Contributing#

Bug reports#

Documentation improvements#

Feature requests and feedback#

Development#

Pull Request Guidelines#

Tips#

Authors#

Special thanks#

Changelog#

0.4.0 (TBD)#

0.3.1 (2024-01-23)#

0.3.0 (2023-02-21)#

0.2.3 (2021-12-30)#

0.2.2 (2020-11-08)#

0.2.1 (2020-03-05)#

0.2.0 (2020-02-01)#

0.1.0 (2019-08-13)#

0.0.4 (2018-12-22)#

0.0.3 (2018-12-04)#

0.0.2 (2018-08-29)#

0.0.1 (2018-06-27)#

Indices and tables#