Project Ortega

Project Ortega is a project to reverse engineer the proprietary firmware of the BCM5719 Gigabit NIC in order to produce documentation sufficient to create a cleanroomed, open source firmware to replace it.

Work structure

RTG: The author maintains a private repository, referred to as RTG (Reversed Tigon). This repository contains C code “raised” from disassembly of the proprietary firmware. This reference codebase enables experimentation and understanding of the functional requirements of any replacement firmware. The objective of the reference codebase is to produce code that, when compiled, is a fully functioning replacement for the original firmware images, thereby proving that the reversed C code is a correct model of the functionality of the original firmware.

Because this C code is derived from proprietary code, it is a derived work of that proprietary code and cannot and will not be published. A cleanroom reverse engineering process undertaken by a separate party will be necessary to produce uncontaminated, open source firmware. To enable this, a natural-language specification for the functional requirements of any firmware for the NIC (to the extent currently understood) is developed from this C code and maintained in RTG. This specification is currently highly incomplete; it is expected to evolve to completeness gradually in response to requests for more information from cleanroom reimplementers.

Ortega: The purpose of the RTG subproject is to enable the development and publication of Ortega. Ortega is a non-contaminated, publishable, open source subset of the RTG dataset. It is derived from RTG whenever RTG is updated by automatically scrubbing all proprietary code from RTG, while leaving in place open source code which was developed as part of the RTG project, such as build and debugging tools, which lack any relation to Broadcom code, as well as the natural-language specification. It is freely available at github.com/hlandau/ortega.

Some build and debug tooling which is part of Ortega is reliant on a small amount of utility code which was derived from Broadcom code, and which is therefore scrubbed in the Ortega repository. Cleanroomers must reimplement these utility functions as described in the specification before they can use these tools.

Communications structure

Communications between reversers (me) and reimplementers should be kept accountable. The intention is for requests for clarification by reimplementers to be made in public channels (e.g. GitHub, IRC), and answered publically (generally by amendments to the repository or IRC).

Status of reversing efforts

• Debug tooling: done. The otgdbg tool provided by RTG/Ortega provides extensive functionality.
• MIPS side
  • Reversing: done. The C codebase derived from disassembly has been completed.
  • Specification: pending reimplementer feedback. The specification is currently a bit of a skeleton but will be fleshed out as requests for more information are received by reimplementers.
  • Build tooling: done. Ortega provides tooling for building images.
• APE side
  • Reversing: pending.
    • Due to the higher complexity of the APE code relative to the MIPS code, combined with the fact that the nature of the APE and its registers is far less known than the by comparison relatively well-documented MIPS side, it is planned to perform the reversing of this code primarily via black box reverse engineering rather than disassembly. This approach has been proven for reversing binaries with extremely high complexity, such as GPU device drivers (Nouveau) and is likely to be more productive. This will require the following in place:
    • Modify an emulator (probably qemu) to run the Cortex-M3 APE code on the host, forwarding register accesses to a remote debugging shell running on the APE. This will allow for easier debugging; unlike the MIPS side, no debugging registers for the APE are exposed to the host. TODO
    • Find a way to inject NC-SI traffic so that the stimulus of the emulated APE code can be observed. TODO
    • Characterise the functionality of the APE and write a proven-working replacement in C as part of RTG. Blocked.
  • Specification: blocked on reversing.
  • Build tooling: done. Ortega provides tooling for building images.

Status of reimplementation efforts

• If you wish to assist with the efforts, please contact me via email, IRC or XMPP.