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: done.
    • Determine how frames are sent to the network from the APE core: done.
    • Determine how frames are received from the network from the APE core: done.
    • Determine how frames are sent to the BMC from the APE core: done.
    • Determine how frames are received from the BMC by the APE core: done.
  • Write a working proof-of-concept replacement in C as part of RTG:
    • Transmission of frames from APE to network: working.
    • Reception of frames from network to APE: working.
    • Transmission of frames to BMC: working for ARP and ICMP. TCP/UDP not yet working, investigating.
    • Reception of frames from BMC: working.
    • Control plane functions (NCSI control packets, etc.): basic functionality working.
    • More initialisation code: TODO.
  • Specification: done, will be revised further on feedback from reimplementers.
  • 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.