Updated Retron 77 (markdown)

Christian Speckner 2018-07-11 23:38:29 +02:00
parent 2977856867
commit 50ba5d382c
1 changed files with 31 additions and 3 deletions

@ -23,7 +23,7 @@ There is no onboard flash memory.
## UART
There is a single UART header on the mainboard that can be used to obtain a serial console to both the U-Boot bootloader and the Linux system running on the device.
There is a single UART header on the mainboard that can be used to obtain a serial console to both the U-Boot bootloader and the linux system running on the device. The UART is configured by both U-Boot and linux at 115200 BAUD.
# Software
@ -51,8 +51,36 @@ Both Stella and Hyperkin's UI use SDL 1.2 for video and audio. SDL runs directly
### UI
The source for Hyperkin's UI is included in the source drop and links against SDL 1.2 and Freetype.
The source for Hyperkin's UI is included in the source drop and links against SDL 1.2 and Freetype. The UI was written by Hyperkin, and the license is unclear.
### Dumper
The cartridge port is driven by the WT51F104S MCU on the main board. The dumper code runs directly on the MCU; the dumper process in linux communicates with the MCU via one of the H3's UARTs. The dumper polls the MCU for cartridge changes (insert and remove). If a cartridge has been inserted, the dumper process tries to read the image from the MCU. As the MCU has only 256 bytes of RAM, the image is read and transferred on the spot.
The cartridge port is driven by the WT51F104S MCU on the main board. The dumper code runs directly on the MCU; the dumper process in linux communicates with the MCU via one of the H3's UARTs. The dumper polls the MCU for cartridge changes (insert and remove). If a cartridge has been inserted, the dumper process tries to read the image from the MCU. As the MCU has only 256 bytes of RAM, the image is read and transferred on the spot. The dumper was written by Hyperkin, and the license is unclear.
### Buttons and joystick ports
The buttons on the backside of the device are directly connected to the H3 via GPIO, the buttons on the front side and the joystick ports sit on the daughter board and connect to the second WT51F104S. A kernel driver (sunxi-atari) is responsible for reading buttons and ports and generating matching keyboard events. The driver communicates with the WT51F104S via I2C and generates keyboard events that are chosen to match Stella's default keybindings. The kernel driver is licensed under the GPL.
## Building
The firmware can be built from scratch on Linux using Hyperkin's source drop and the Makefiles contained therein. The source drop contains the Linaro ARM toolchain, only standard Linux tools are required for building.
# Setup and boot process
## Firmware image and bootloader
The SD image generated by the build process contains the bootloader in the first few sectors after the MBR / partition table. [U-Boot](https://www.denx.de/wiki/U-Boot) is used to boot the system. On powerup, the CPU starts from a ROM embedded into the H3 (BROM). The BROM then tries to load the bootloader from SD. The boot process is standard for Alwinner SOCs and. documented [here](http://linux-sunxi.org/Boot_Process). The U-Boot console can be accessed from a serial terminal is connected to the UART header on the board (see above).
## Linux boot
Immediately after the bootloader, the SD card contains a single FAT32 partition. From there, U-Boot reads a script file (`boot.scr`). This script loads the kernel image from the `uImage` file and boots into linux.
## Root file system and system lifecycle
The boot process builds the root filesystem of the device as an initramfs into the kernel. The initramfs is never unmounted and contains everything, including all binaries and libraries. The FAT32 partition is mounted under `/mnt`. On boot, a serial terminal is started on ttyS0 and can be accessed via the UART header on the board (see above). On startup, init starts the dumper process which keeps running until the console is switched off. The dumper communicates with the WT51F104S MCU connected to the cartridge port via ttyS2 and executes command shell commands. The program flow looks like this:
1. Check whether a cartridge is inserted or removed
2. If a cartridge is inserted, try to dump the image
3. If no cartridge is inserted on startup or a cartridge is removed, kill the running Stella / UI process and start the UI
4. If the dump was successful, kill the running UI / Stella process and launch Stella for the dumped image
5. If the dump was unsuccessful, kill the running Stella / UI process and start the UI