Metadata-Version: 2.4
Name: isaac-toolkit
Version: 0.5.7
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tqdm
Requires-Dist: pyyaml
Requires-Dist: pyelftools
Requires-Dist: pandas>=2.1
Requires-Dist: dacite
Requires-Dist: matplotlib
Requires-Dist: leb128
Requires-Dist: fastparquet
Requires-Dist: pyarrow
Requires-Dist: mapfile-parser
Requires-Dist: gprof2dot
Requires-Dist: capstone
Requires-Dist: networkx<3.0.0,>=2.5.1
Requires-Dist: setuptools-rust
Requires-Dist: cpp-demangle==0.1.2; python_version < "3.11"
Requires-Dist: weasyprint
Requires-Dist: tabulate
Requires-Dist: jinja2
Requires-Dist: lz4
Requires-Dist: zstandard
Requires-Dist: zstd
Requires-Dist: humanize
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black~=24.4.2; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: licenseheaders; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: memgraph
Requires-Dist: neo4j; extra == "memgraph"
Requires-Dist: pygraphviz; extra == "memgraph"
Dynamic: license-file

# isaac-toolkit
Automated Customization Toolkit for Instruction Set Architectures (ISAs)

## Repository Structure

### Python Package

```python
isaac_toolkit
├── algorithm
│   └── ... # work in progress
├── analysis
│   ├── dynamic  # dynamic analysis tools
│   │   ├── histogram
│   │   │   ├── instr.py
│   │   │   ├── opcode.py
│   │   │   └── pc.py
│   │   ├── profile
│   │   │   └── profile.py
│   │   └── trace
│   │       ├── basic_blocks.py
│   │       ├── instr_operands.py
│   │       ├── track_used_functions.py
│   │       └── trunc_trace.py
│   └── static  # static analysis tools
│       ├── dwarf.py
│       ├── histogram
│       │   ├── disass_instr.py
│       │   └── disass_opcode.py
│       ├── linker_map.py
│       ├── llvm_bbs.py
│       └── mem_footprint.py
├── artifact
│   └── artifact.py
├── backend  # ISAAC backends
│   ├── isa  # not implemented
│   │   └── ...
│   ├── ise  # not implemented
│   │   └── ...
│   ├── memgraph  # annotate CFDG database with bb_weights
│   │   └── annotate_bb_weights.py
│   └── profile  # not implemented
│       └── ...
├── frontend  # ISAAC frontends
│   ├── cfg  # configuration parsing
│   │   └── yaml.py
│   ├── disass
│   │   └── objdump.py
│   ├── elf
│   │   └── riscv.py
│   ├── instr_trace
│   │   ├── etiss.py
│   │   └── spike.py
│   ├── isa  # work in progress
│   │   └── ...
│   ├── linker_map.py
│   ├── memgraph  # work in progress
│   │   ├── llvm_ir_cdfg.py
│   │   └── llvm_mir_cdfg.py
│   ├── mem_trace  # not implemented
│   │   └── ...
│   └── source  # not implemented
│       └── ...
├── generate  # ISAAC generators
│   ├── ise  # Propose ISAXes
│   │   ├── choose_bbs.py
│   │   ├── pool
│   │   │   └── random.py
│   │   └── query_candidates_from_db.py
│   └── iss  # ISS retargeting
│       └── generate_etiss_core.py
├── session  # Infrastructure for sessions/artifacts
│   ├── artifact.py
│   ├── config.py
│   ├── create.py
│   ├── session.py
│   └── summary.py
├── utils
│   ├── cli.py
│   ├── nx_converter.py  # Nextworkx graph to images
│   ├── pickle_printer.py  # Convert pickle files (including DFs to text)
│   └── ...
└── visualize
    └── pie  # Pie chart generators
        ├── disass_counts.py
        ├── mem_footprint.py
        └── runtime.py
```

### Examples


## Usage

### Prerequisites

Install (optional) APT Requirements:
sudo apt install libgraphviz-dev

Setup a Python virtual environment:

```sh
virtualenv -p python3 venv/
# Alternative: python3 -m venv venv/
```

Install packages:

```sh
pip install -e .

# Optional:
pip install -e ".[dev]"
pip install -e ".[memgraph]"
```

### Demo

~~Package installation: TODO~~

Make sure to add the top level directory of this repository to your Python path:

```sh
export PYTHONPATH=$(pwd):$PYTHONPATH
```

For Python v3.10+ you can also just use `pip install -e .`!

Minimal example:

```sh
python3 -m isaac_toolkit.session.create --session sess/
python3 -m isaac_toolkit.session.summary --session sess/
```

See [`Examples/standalone/coremark/README.md`](Examples/README.md) for an end-to-end example.

## Development

### Style

We use the [`black`](https://black.readthedocs.io/en/stable/) formatter to maintain a consistent Python style (See `setup.cfg` & `pyproject.toml`)

Pylint config is also available, but not enforced.

### Testing

First, make sure that the additional development packages are installed via:

```sh
pip install -r requirements_dev.txt
```

Run Pytest:

```sh
python3 -m pytest tests -rs -s
```

Create Coverage Report:

```sh
coverage run --source isaac_toolkit -m pytest tests
coverage report -m
coverage html
```
