Metadata-Version: 2.4
Name: nyxstone-tricore-gcc
Version: 0.2.0
Summary: In-process TriCore assembler/disassembler, Python bindings around binutils-tricore (gas + libopcodes).
Author: emproof
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/emproof-com/NyxstoneTricoreGCC
Project-URL: Repository, https://github.com/emproof-com/NyxstoneTricoreGCC
Project-URL: Issues, https://github.com/emproof-com/NyxstoneTricoreGCC/issues
Project-URL: Documentation, https://github.com/emproof-com/NyxstoneTricoreGCC#readme
Keywords: tricore,assembler,disassembler,embedded,infineon,binutils
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Assemblers
Classifier: Topic :: Software Development :: Disassemblers
Classifier: Topic :: Software Development :: Embedded Systems
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cffi>=1.16
Dynamic: license-file

# nyxstone-tricore-gcc (Python)

Python bindings to the [NyxstoneTricoreGCC](..) in-process TriCore
assembler/disassembler.

Uses CFFI to compile a small C extension directly from the C++/C wrapper
sources, linking in the bundled binutils-tricore prebuilt archives and gas
object files.  The build is self-contained -- no prior `make` step and no
runtime shared library needed.

The API mirrors that of the sibling project
[Nyxstone](https://github.com/emproof-com/nyxstone) (LLVM-MC based, covers
LLVM-supported architectures; this package uses GNU binutils for TriCore).
Six methods: `assemble`, `assemble_to_instructions`, `disassemble`, and
`disassemble_to_instructions` mirror Nyxstone, plus `assemble_with_relocs`
and `assemble_to_instructions_with_relocs` for `gas -r`-style relocation
output.  Each takes an absolute `address` (and for the assembly entry
points, an iterable of `LabelDefinition`).

## Install

```sh
pip install ./    # from the python/ directory
```

Or develop in-place:

```sh
python setup.py build_ext --inplace
PYTHONPATH=. python examples/smoke.py
```

## Usage

```python
from nyxstone_tricore_gcc import LabelDefinition, NyxstoneTricoreGCC

nx = NyxstoneTricoreGCC()

# Assemble.  Local branches get their displacement encoded directly.
bytes_ = nx.assemble("start:\n nop\n j here\nhere:\n ret\n", address=0)
assert bytes_ == b"\x00\x00\x3c\x01\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

```python
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.
