nyxstone-tricore-gcc 0.1.2

In-process TriCore assembler/disassembler, Python bindings around binutils-tricore (gas + libopcodes).

nyxstone-tricore-gcc (Python)

Python bindings to the NyxstoneTricoreGCC in-process TriCore assembler/disassembler.

Uses CFFI to compile a small C extension that statically links the C++ side (libnyxstone_tricore.a) and the binutils archives. No runtime shared library needed.

The API mirrors that of the sibling project Nyxstone (LLVM-MC based, covers LLVM-supported architectures; this package uses GNU binutils for TriCore). Four methods named assemble, assemble_to_instructions, disassemble, and disassemble_to_instructions, each taking an absolute address (and for the assembly entry points, an iterable of LabelDefinition).

Install

The C++ library must be built first:

(cd ..; make)

Then install the Python package:

pip install ./    # from the python/ directory

Or develop in-place:

python setup.py build_ext --inplace
python examples/smoke.py

Usage

from nyxstone_tricore_gcc import LabelDefinition, NyxstoneTricoreGCC

nx = NyxstoneTricoreGCC()

# Assemble.
bytes_ = nx.assemble("start:\n nop\n j here\nhere:\n ret\n", address=0)
assert bytes_ == b"\x00\x00\x1d\x00\x00\x00\x00\x90"

# Assemble with an external label.
bytes2 = nx.assemble(
    "nop\n j ext\n",
    address=0x1000,
    labels=[LabelDefinition("ext", 0x2000)],
)

# Disassemble to instructions.
for ins in nx.disassemble_to_instructions(bytes_, address=0x80000000):
    print(f"0x{ins.address:08x}  {ins.assembly}")

# Or as a single string.
print(nx.disassemble(bytes_, address=0x80000000))

# Limit the number of instructions decoded.
first_two = nx.disassemble_to_instructions(bytes_, address=0, count=2)

Errors

from nyxstone_tricore_gcc import NyxstoneTricoreGCC, AssembleError, SectionViolationError

nx = NyxstoneTricoreGCC()

try:
    nx.assemble("not_a_real_mnemonic %d4")
except AssembleError as e:
    print("encoder failed:", e)

try:
    nx.assemble(".data\n .byte 0x42\n")
except (SectionViolationError, AssembleError) as e:
    # The library is .text-only; data/bss/section .foo are rejected.
    print("non-.text section:", e)

Threading

Methods are safe to call from multiple threads, a process-wide threading.Lock serializes them.