From ba615f1cd5cac277d7bcc76547b72c5191d676f4 Mon Sep 17 00:00:00 2001 From: Samuel Holland Date: Thu, 26 Oct 2017 21:16:42 -0500 Subject: [PATCH] project: Add README --- README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4a7d17d --- /dev/null +++ b/README.md @@ -0,0 +1,79 @@ +# Overview + +The goal of this project is to understand the various blobs provided by +Allwinner for their `sunxi` series of ARM SoCs. This includes understanding the +interfaces the blobs provide and the bits of undocumented hardware they use. +Currently, the tools in this repository are set up to process two types of +blobs: the boot ROMs and the ARISC firmware. + +From the original, untouched blobs, the tools here can generate ELF objects with +symbols, annotated assembly listings, and SVG graphs documenting the control +flow of code within the blob. + +## Boot ROMs (BROM) + +The boot ROM, is flashed into the SoC hardware, and is generally the same for +every chip of the same model. It comes in two flavors: normal (NBROM) and secure +(SBROM). The secure boot ROM is much larger and more complicated because it must +verify the next stage of firmware before running it. Unfortunately, only one of +the ROMs is visible at a time, depending on the state of the device's "secure +boot" eFuse. + +The BROM blobs in this repository were dumped from running devices using `md` +from within u-boot. + +## ARISC firmware + +These files are closed-source firmware provided by Allwinner with their board +support package (BSP), usually with the name `scp.bin`. Slightly different +versions of the firmware are provided in the BSPs from different board +manufacturers. By looking at the changes between versions (and knowing the order +from the embedded version number), we can determine the history of changes made +to the firmware. + +While the firmware is proprietary, source code is provided in an AES-encrypted +tarball in [various released Linux kernel trees][tinalinux]. + +[tinalinux]: +https://github.com/tinalinux/linux-3.10/tree/r18-v0.9/drivers/arisc/binary + +# Prerequisites + +These tools require a cross `binutils` (or full toolchain) for each architecture +of blobs you want to process. Note that even on SoCs that support AArch64, the +BROM is still AArch32, so you will need ARM cross tools for them. Cross +toolchains can be downloaded from Linaro for ARM, [GitHub][or1k-toolchains] for +OpenRISC, or they can be built manually with [musl-cross-make][musl-cross-make]. +If your cross toolchain is named differently, edit the top of the `Makefile` to +provide your path or prefix. + +[musl-cross-make]: https://github.com/smaeul/musl-cross-make +[or1k-toolchains]: https://github.com/openrisc/or1k-gcc/releases + +Beyond that, the scripts only require `bash` and standard POSIX utilities. + +# Using the tools + +`make BLOB=/` will build a single blob all the way from the +hexdump to the call graph. You can simply run `make` to build all files for all +blobs. You can run `make //` for any file (`annotated.s` +`blob.elf`, `blob.s`, `callgraph.dot`, and `callgraph.svg`) to only make that +file and its dependencies. + +There are some additional scripts that are useful for processing newly-found +blobs or forr other specific use cases. They are not hooked up to the +`Makefile`, so they must be run manually. Documentation is at the top of each +script. + +# Contributing + +After modifying the annotations in `annotated.s`, run `make save` to copy them +back to the `comments` file. You can then commit your changes to `comments`. If +you find a new, previously-unmarked function, create a symbol for it in the +`symbols` file. *Add two blank lines before the first instruction in +`annotated.s` and run `make save` before running `make` again*. This is +important to keep the comments aligned, as `objdump` will place a blank line and +a line with the symbol name before the function. + +Please run `make check` to check the consistency of your symbols and sections +files.