# Jacking (Jazelle hacking (Jean gazelle hacking))

**Jazelle reverse engineering effort**

not the first one, but hopefully one that properly documents some stuff

## Workflow

### Cypress FX3

```
$ # compile:
$ make
$ # launch OpenOCD background process (needs to be done once):
$ make openocd-launch
$ # run & debug code
$ make openocd-load && make gdb
```

Needs an `arm-none-eabi` toolchain, and OpenOCD.

### Raspberry Pi v1.x bare-metal

```
$ # compile:
$ make -C rpi/
$ # now copy rpi/rpi.img to your microSD card and name it "kernel.img".
$ # alternatively, use OpenOCD again:
$ make launch-openocd
$ make openocd-load && make gdb
```

Needs an `arm-none-eabi` toolchain, and optionally OpenOCD. Output is written
to the UART on pin 8 (TX).

Most likely won't work on a v2 or higher.

### Linux userspace

Currently only tested on a Raspberry Pi v1.2 B+. May also work on Linux running
on a Zynq.

```
$ # native compilation:
CFLAGS=-mtune=native make -C linux
$ # cross-compilation: (change the -march depending on your target)
CC=arm-linux-gnueabihf-gcc CFLAGS=-march=arm1176jzf-s make -C linux
$ # run it
$ linux/jazelle
```

Requires an `arm-linux-gnueabihf` toolchain.

### Xilinx Zynq bare-metal

***NOTE: HIGHLY EXPERIMENTAL!***

```
$ make -C zynq jazelle.o
```

Then link `zynq/jazelle.o` into an XSDK/Vitis project. If things break, the
first thing you should try is replacing the cache routines with the ones from
the Xilinx libraries.

Requires an `arm-none-eabi` toolchain.

### Other ports

There are still several platforms out there which (most likely) can also run
Jazelle, but that don't have a port yet. See the [TODO](#TODO) header.

## Credits

FX3 base code: gratuitously stolen from https://github.com/zeldin/fx3lafw/

Cache manipulation code was inspired by code from libnds (ARM9), libn3ds
(ARM11), and Xilinx' embeddedsw (Cortex-A9).

Jazelle info this project is based on:
* https://hackspire.org/index.php/Jazelle
* https://github.com/SonoSooS/libjz

## TODO

* Figure out Jazelle stuff:
  * [ ] Which bytecode instructions are supported on which Jazelle versions?
  * [x] How exactly does the stack work? (When a handler function is being called)
  * [ ] How exactly does the Jazelle status register work?
  * [ ] What control registers are there that influence the execution?
    * [ ] Is it possible to force execute a certain instruction using the handler
          instead of the default in-hardware execution?
      * Apparently not?
    * [ ] ...
  * [x] How does one call regular ARM/Thumb code from inside Jazelle?
    * invokeXYZ instruction implementation: check method reference string, do
      things based on that
  * [ ] ...
  * [ ] Verify what Hackspire and libjz have, to check if it is correct
  * [ ] Look at what Hackspire and libjz don't have and try to complete it
* Ports:
  * [ ] TI Nspire
  * [x] Cypress FX3
  * [x] Raspberry Pi v1 baremetal
  * [x] Linux userspace
  * [ ] Linux kernel module
  * [ ] 3DS homebrew
  * [ ] Xilinx Zynq
  * [ ] BeagleBoard/BeagleBone/PocketBeagle? (any OMAP or TI Sitara AM335x,
        most likely not the AM572x-based ones, and definitely not the BeagleV)
  * ...