Package: elli
ElliElli is a python library for reading, manipulating, merging, and writing intel hex files, raw binary files, or operating on memory slices in general.Common use cases at a glanceThe most common use cases for Elli are reading, merging, and writing hex files,
as well as converting binary files to hex files or vice versa.fromelliimportEllifrompathlibimportPath# Merge hex filesfile_one=Elli("/path/to/one.hex")file_two=Elli("/path/to/two.hex")merged=file_one.merge(file_two,allow_overwrites=False)output=Path("/path/to/merged/output.hex")merged.write(output,"hex")# Convert a binary file to a hex filebin_file=Path("/path/to/file.bin")hex_file=Path("/path/to/file.hex")el=Elli(bin_file.read_bytes())el.write(hex_file,"hex")In depth usageThe classElliis the main workhorse of this package.
To get started, you'll want something along the lines offromelliimportElliConstructionTo construct an object of the class Elli, you have a few options:# Read and parse an intel hex fileel=Elli("/path/to/file.hex")# The same, but using `Path` from the standard library `pathlib`frompathlibimportPathhex_file=Path("/path/to/file.hex")el=Elli(hex_file)# Construct from a python dictionary representing the relevant memoryel=Elli({0:190,1:241,2:140,3:213})# Construct from raw bytes. This assumes a start address of 0el=Elli(bytes([1,2,3,4]))Basic memory manipulationMemory in the Elli can be set byte-wise, or word-wise (a word being 4 bytes):# Get and set individual bytesbyte=el[0xae1f3256]el[0xae1f3256]=byte-15# Get and set whole words without alignment requirementsword=el.get_word(0xae1f3256)el.set_word(0xae1f3256,0)Query memory slice informationInformation about the contents of Ellis are available with built in operators.# Check whether an address is present in an Elliel=Elli({1:1,2:2})address=1addressinel# Trueaddress=3addressinel# False# Check whether two Ellis have the same memory contentother=Elli({1:1,2:2})el==other# Trueother[3]=3el==other# False# Get the span of an Elli. The span being lower and upper bounds in# the address space of an Ellispan_el=el.span# (1, 2)span_other=other.span# (1, 3)# Get and set start addresses of Ellisstart=el.start_address# 1# Setting the start address shifts all memory along with the new start addressel.start_address=3# {1: 1, 2: 2} -> {3: 1, 4: 2}Merge and obtain sub-ranges of EllisElli can merge and split memory content.one=Elli("/path/to/file_one.hex")two=Elli("/path/to/file_two.hex")# Merge `one` and `two` into a new Elli, raising a `ValueError` on collisionsthree=one.merge(two)# To overwrite collisions, taking values from `two`three=one.merge(two,allow_overwrites=True)# Create an Elli with a subset of the memory of `three`, from address# `start_address`, up to and including address `end_address`start_address=0x2567end_address=0x31abfour=three.range(start_address,end_address)Intel hex related operationsElli can get and set intel hex specific memory information.# Get and set the `Start segment address` of an Ellics,ip=el.hex_start_segment_addressel.hex_start_segment_address=new_cs,new_ip# Or clear such information from the Elliel.hex_start_segment_address=None# Get and set the `Start linear address` of an Elliexec_start=el.hex_start_linear_addrssel.hex_start_linear_address=new_exec_start# Or clear such information from the Elliel.hex_start_linear_address=NoneExport an Elli to different formatsEllis can be exported as intel hex, python dictionaries, or raw bytes.# Get a string representation of an intel hex filehex_string=el.to_hex()# Get a binary blob representing all the bytes of the Elli,# with `fill` used for addresses that are not setbyte_string=el.to_bin(fill=0xFF)# Get a python dictionary of the underlying memory,# mapping addresses to bytesmapping=el.to_dict()Write Ellis to filesAn Elli can be directly written to a file as either an intel hex file, or a raw binary file.# Write an intel hex fileel.write("/path/to/file.hex","hex")# Write a raw binary file, setting unspecified byte values to `0xFF`el.write("/path/to/file.bin","bin",fill=0xFF)Contribution guidelinesElli should remain a slim and lightweight piece of software.
As such, the python standard library should be used over third party packages as far as possible.Elli's code is formatted withblack.Elli's code should run error free throughpylint,pyflakes,mypy, andpycodestyle.
The followingpycodestyleoptions can be disabled:E203: whitespace before ":"E402: module level import not at top of file