README.md

Fernly - Fernvale Reversing OS

Fernly is a simple operating system designed for use in the reverse engineering
of the Fernvale CPU. It will likely be disposed of when the system has been
understood well enough to implement a full operating system.

Running Fernly

This will open up /dev/fernvale, load usb-loader.bin as a stage 1 bootloader,
and then load (and jump to) firmware.bin as stage 2. Optionally, you can add
a stage 3 file by specifying it as an additional argument.

Many 3rd-party devices enter bootloader mode only for a short window (~1s)
after being connected to USB. A device almost certainly should be "off". Some
devices require that battery is removed, while some - don't. To accommodate
such cases, there's -w (wait) option. Run fernly-usb-loader, and only
then connect a device to USB. This will allow to try various combinations
mentioned above with greater comfort (you need to disconnect and poweroff
device after each try, and restart fernly-usb-loader).

OSX Notes

The default OSX CDC matching seems to miss the Fernvale board. Use fernvale-osx-codeless to get a com port.

SPI and Flashrom

Fernly includes a special 'flashrom' mode that allows for direct communication
with the flashrom program to manipulate the onboard SPI. The protocol is
binary, and can be entered by issuing the following command:

spi flashrom

Fernly will respond with a binary 0x05, indicating it is ready.

The format of the protocol is very simple. The host writes the number of bytes
to write, then the number of bytes to read, and then writes the data to send
to the flash chip. It then reads the requested number of bytes. For
example, to send a 2-byte command '0xfe 0xfa' followed by a 3-byte response,
write the following data to the serial port:

| 02 03 fe fa |

Then read three bytes of data from the serial port.

A maximum of 255 bytes may be transmitted and received at one time, though
in practice these numbers may be smaller.

To exit 'spi flashrom' mode and return to fernly, read/write zero bytes.
That is, send the following packet:

| 00 00 |

See ROM-BACKUP.txt for user-level instructions how to backup/restore
FlashROM of your device.

Licensing

Fernly is licensed under the BSD 2-clause license (see LICENSE).

Previous versions of fernly linked against division libraries taken from U-Boot,
which were licensed under GPL-2. These files have been removed.

Instead, we supply a version of libgcc.a. This file was extracted from a
standard gcc toolchain, specifically: