= Pine64's BL602 reverse engineering working group

== Notes

• The blobs were compiled using riscv32-unknown-elf-gcc_8.3.0 -march=rv32imfc -mabi=ilp32f -gdwarf -Os -std=gnu99 -ffunction-sections -fdata-sections -fstrict-volatile-bitfields -fshort-enums -ffreestanding -fno-strict-aliasing

• The target likely supports atomics. If so we may use -march=rv32imafc.

== Toolset

• Our funcdiff.py and headerdiff.py tools. See link:script/README.md[their documentation]

• https://github.com/riscv/riscv-gnu-toolchain[RISC-V GNU Compiler Toolchain]

• https://ghidra-sre.org/[Ghidra], an IDA-like RE suite courtesy of the NSA. Use https://github.com/ElementW/ghidra[this fork] if you want to load RISC-V binaries that have relocations (i.e. unlinked bins)

• https://cutter.re/[Cutter], a graphical frontend for https://www.radare.org/r/[radare2]

• https://github.com/sevaa/dwex[DWARF Explorer], an explorer for DWARF debugging data ** The proprietary libraries still contain DWARF data, but tool support for showing it varies greatly. This will show you the raw DWARF information (e.g. structures, function local variables, inlined function information).

• Add your favorite disassembly tools here. If the tool is not free, mark it with (non-free).

== Where to get started

WiFi and BLE-related binaries available in the BL602 are included within this repo:

• blobs/ contains .a files of the libraries along with compiled examples of their use, as .elf.

• images/ has .bin files of factory PineCone firmware. See link:images/README.md[the README for the directory].

• libatcmd/, libbl602_wifi/ and libblecontroller/ contain disassembled binaries of the libraries' object files, along with disassembly of their respective example app.

Sources that are being reverse engineered are located in components/, and reconstructed headers are in dwarf/ and headers/. Tooling is available in the script/ directory.

[IMPORTANT] .Using proprietary RivieraWaves code

This reverse-engineering project tries to stay clear of any possible copyright problems coming from RivieraWaves; i.e. the goal is https://en.wikipedia.org/wiki/Clean_room_design[clean-room RE]. Whatever you do, do not insert proprietary Copyright (C) RivieraWaves code in the sources in components/ if this code isn't available in the BL602 SDK! RivieraWaves code is known to be easily available on GitHub with simple searches, but avoid looking at it, unless you wish to forfeit your right to directly contribute code here.

== Resources

• https://github.com/pine64/bl602-docs[Pine64 SDK fork's documentation], if you figure something out that's documentation-worthy, please update that documentation.

• https://github.com/pine64/bl602-docs/blob/main/mirrored/BL602_BL604_DS_1.6_en.pdf[BL602/BL604 Datasheet]

• https://github.com/pine64/bl602-docs/blob/main/mirrored/BL602_BL604_RM_1.2_en.pdf[BL602/BL604 Reference Manual]

• https://github.com/pine64/bl_iot_sdk[SDK]

• https://github.com/bouffalolab/bl_docs/raw/main/BL602_ISP/en/BL602_ISP_protocol.pdf[BL602 ISP Protocol Documentation]

• https://github.com/bouffalolab/BLOpenFlasher[Official Open-Source Flasher for Bouffalo Chips]

• https://pine64.gami.ee/bl602/HF-LPS170_Linus_Driver_20200924.zip[Linux Driver and Firmware for SDIO WiFi & BT Module based on BL602]

== Work log (top-down append-only)

=== WildCryptoFox (29 Oct 2020)

• Initialized README.adoc and copied LICENSE from the SDK.

• Split objects out of archives ar x libx.a.

• Disassembled objects to their assembly git/github/pine64/bl_iot_sdk/toolchain/riscv/Linux/bin/riscv64-unknown-elf-objdump -d -r xx.o"

=== Yangff (30 Oct 2020)

• Added three statically linked elf built from bl_iot_sdk to provide clear symbols for reverse engineering

• The three examples are from commit 9a10205e96a6b10e22069c87625550cad666b1b4, bl602_demo_at, bl602_demo_wifi and sdk_app_ble_sync.

• They are compiled with the riscv toolchain shipped with the sdk and using make -j directly in the folders with CONFIG_CHIP_NAME=BL602 and CONFIG_LINK_ROM=1. The disassembly is generated with riscv64-unknown-elf-objdump -d ./x.elf > ./x.S