D11emu is an open-source emulation framework for Broadcom’s IEEE 802.11 MAC implementation, namely D11. In combination with our corresponding firmware patch for the WiFi chip, this framework enables essential debugging methods, including microcode breakpoints and D11 state extraction. This toolset allows researchers to analyze the D11 microcode in a controlled environment dynamically.

We encourage everyone interested to enter the game, roll the D11, and provide new insights on Broadcom’s MAC implementation.

For more insights into the D11 architecture and an overview of the emulator's internals, read our paper Rolling the D11: An Emulation Game for the Whole BCM43 Family.

The D11 Emulator is designed to be connected to a Raspberry Pi 3 Model B+ or Raspberry Pi 4 Model B. The bcm43455c0 WiFi SoC of the attached device must run a modified firmware. Nevertheless, the D11 Emulator can be used as a standalone application. In this case, state extraction features cannot be used. The D11 Debug Controller is part of the utilities.

1. Install Rust and Cargo
2. Clone this repository and enter the created directory.
3. Update configuration. (see Config Section below)
4. Make sure the b43-asm assembler version 3 is installed and accessible in your PATH. It is part of the Nexmon repository and can be installed by running the following commands:

   cd nexmon
   source setup_env.sh
   cd buildtools/b43-v3/assembler/
   make
   sudo make install
   

   The assembler is needed to assemble the microcode files located in tests/*.asm. They are needed to conduct the unit tests of the project, and therefore, are assembled during the build process of the emulator. If you just build the project and don't want to conduct the unit tests (cargo test), you can remove the following line from the Cargo.toml file:

   build = "build.rs"
   

5. Execute cargo run -- {PATH_TO_UCODE_BINARY} to start the emulator. To build and execute an optimized binary use cargo run --release -- {PATH_TO_UCODE_BINARY}. For further build options, please consult the Rust and Cargo documentation. To build the project without running, you can use cargo build or cargo build --release.

To enable state extraction of a real device, please refer to our D11debug repository.

Configuration is written into src/config.rs. Two constants of the file must be updated before the first use of the emulator:

• TARGET_IP_ADDRESS: Username and IP address of the instrumented device, e.g., [email protected].
• TARGET_SSH_KEY_LOCATION: Location of the SSH Key to connect to the instrumented device, e.g., /home/david/.ssh/pi_key.

After changing the configuration, rebuild the project by running cargo build or cargo run -- {PATH_TO_UCODE_BINARY}.

D11 microcode binaries are included in the firmware files shipped with Nexmon. Please refer to Nexmon or our D11 debug patch repository on how to build and extract microcode binaries.

You can generate and open an html documentation of the project by running cargo doc --open.

The D11 Emulator is designed to interpret a D11 microcode binary, assembled for D11 rev. 15 up to rev. 54. It was tested on rev. 46 and 54.

The D11 Emulator needs a path to a microcode binary as program argument. After startup it offers an interactive CLI to the user. Available commands are explained briefly in the following section.

This project contains several Python helper utilities. They are located in the folder utilities and described here.

If any use of this work results in an academic publications, please include citations to the paper cited under (1), this software (2), and the Nexmon project (2).

1. Jakob Link, David Breuer, Francesco Gringoli, and Matthias Hollick. 2023. Rolling the D11: An Emulation Game for the Whole BCM43 Family. In The 17th ACM Workshop on Wireless Network Testbeds, Experimental evaluation & Characterization 2023 (ACM WiNTECH’ 23), October 6, 2023, Madrid, Spain. ACM, New York, NY, USA, 8 pages. https://doi.org/10.1145/3615453.3616520
2. Jakob Link, David Breuer, Francesco Gringoli, and Matthias Hollick. 2023. D11emu: A BCM43 D11 Emulation Framework. https://github.com/seemoo-lab/d11-emu
3. Matthias Schulz, Daniel Wegemer and Matthias Hollick. Nexmon: The C-based Firmware Patching Framework. https://nexmon.org

• David Breuer [email protected]
• Jakob Link [email protected]