mmiogrok/README.md

# mmiogrok

Collection of Python libraries to parse, generate and convert between several
MMIO register definition files.

#### Parse and generate

* ARM CMSIS-**SVD** (ARM etc.)
* **Device tree** (source/binary, peripheral only, no registers) [*planned*]

#### Parse only

* NEC/Renesas **DVF** (78K, RL78, V830/RH830, RX)
* Lauterbach TRACE32 **PER** (misc) [*work in progress*]
* Atmel/Microchip **ATDF**/ATpack (AVR etc.) [*planned*]
* Texas Instruments **DSLite** (MSP430 etc.) [*planned*]

#### Convert

* DVF → SVD
* PER → SVD [*work in progress*]
* ATDF → SVD [*planned*]
* DSLite → SVD [*planned*]
* SVD → DTS/DTB (peripherals only) [*planned*]
* DTS/DTB → SVD (peripherals only) [*planned*]

## Usage

#### Libraries

* `dvf/dvfparse.py` is able to parse DVF files
* `svd/svd.py`, `svd/svdparse.py`, `svd/svdgen.py` handle SVD files

#### Utilities

* `dvf/dvf2h.py` is a quick DVF-to-headerfile converter
* `dvf2svd.py` converts DVF to SVD files using the above libraries

## Dependencies

Python stdlib only, though I've been using 3.10, it might be the case that some
things aren't in eg. 3.6.

## FAQ etc

#### Why is it Python? Why is the Python code so hacky?

I quickly wanted to get something to work so that I could import MMIO stuff in
Ghidra. Yes the code could be cleaner/faster (especially with a resp. Racket or
Rust rewrite), but I just wanted to Get Things Done.

#### Why is it not a proper Python module?

I started from a script and things evolved from there. I should probably
restructure the codebase a bit, the current method of importing stuff (by
adding things to the Python module path...) is, not a good idea.

#### Why are the converters inaccurate?

For DVF, the main problem lies in the file format: all registers are laid out
without peripheral associations, so no peripheral information (and peripheral ↔
interrupt) mapping is available. Furthermore, the file format is binary, so
figuring out which exact bits correspond to which register properties (eg.
'write-to-clear') is pretty hard. The basics are still there, though. The code
is currently untested for V830 and RX DVF files, which might differ in some
ways.

For TRACE32 PER, a large problem is that these files mix UI elements,
conditionals and loops, and actual peripheral and register definitions, in a
quite shitty to parse text-based format, making things quite complicated. The
conditionals depend on outside knowledge (eg. exact chip names, Xtensa TRAX
register bases, ...) which I don't have, so those are currently left ignored.

#### Where do I get these files?

CMSIS-SVD files can be obtained from eg.
[here](https://github.com/posborne/cmsis-svd).

Many device tree source files can be found in the [Linux kernel source
tree](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/).

NEC/Renesas DVF files can be downloaded from the Renesas website (per chip as
"Device File" or "Parameter File"), or in bulk from Renesas toolchain updates
or from messing around with the search tool on the Renesas webiste.

TRACE32 PER files can be obtained from the Lauterbach website by going through
the "Other Updates" section of the TRACE32 downloadables.

ATpack files (which are zip files containing ATDFs) can be downloaded from
[here](http://packs.download.atmel.com/).

TI DSLite files come with a CCStudio installation.

## License

Eh, idk yet.