Metadata-Version: 2.4
Name: nyxstone-tricore-gcc
Version: 0.1.2
Summary: In-process TriCore assembler/disassembler, Python bindings around binutils-tricore (gas + libopcodes).
Author: emproof
License: 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: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
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
Requires-Dist: cffi>=1.16

# 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](https://github.com/emproof-com/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:

```sh
(cd ..; make)
```

Then install the Python package:

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

Or develop in-place:

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

## Usage

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

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