RTLPlayground
A Playground for Firmware development for advanced user of RTL8372/RTL8373 based 2.5GBit Switches.
For each hardware configuration of these devices, there is usually a managed and an
unmanaged version sold, with mostly identical hardware. The aim is to provide management
features also for unmanaged devices with additional features such as Management VLAN,
DHCP servers, multi-language support, IPv6 and TLS-encrypted web-pages. At present, however
only the following features are provided:
- A modern web-interface with mouse-over to display further information
- A serial console interface to configure all features
- IGMP to configure Multicast streaming
- Port configuration showing detailed information about own and Link-partner advertised
Speed settings and configuration of these settings on the local side
- Per-port configuration of frame sizes (MTUs) for Jumbo-Frame support or limiting MTUs
for particular devices
- EEE (Energy Efficient Ethernet) can be configured per-port. Detailed information is
provided for support offered by the link partner and the EEE status of a port.
- VLAN configuration
- SFP information is displayed on the inserted modules, the current sensor values such as
temperatures, RX and TX power are displayed in the CLI and as mouse-over on the web
- Mirror configuration
- Link Aggregation Groups can be set up
- Detailed information on port packet statistics
- Configuration saved to flash via the web-interface
- Firmware updates via the web
- Installation as a firmware upgrade from the original web-interface
While the firmware provides already considerable improvements over the original managed firmware,
the firmware still lacks support for the proprietary loop prevention
protocols as well as DHCP. Spanning Tree is available (see doc/stp.md), but is
a simplified implementation - read that document before enabling it on a
switch you administer over the network. If you need these features, do not install the playground on your managed
devices. In any case, installation is strongly discouraged unless you can at least make
a backup of the original flash content via a SOIC clamp such as also used for BIOS
backups and can re-install that firmware in case something is wrong. For this no soldering
skills are necessary.
The firmware supports all hardware features of devices with
- 4 2.5GBit ports + 2 SFP+ ports
- 5 2.5GBIT + 1 SFP+ port
- 8 2.5GBit + 1 SFP+ port
Devices sold usually have a fairly common design, however there may be differences in the LED
configuration (switches have LEDs with different colours and use types of LEDs). The list
of tested devices can be found in Supported devices.
To do meaningful development you will need to use a serial console, so soldering skills
are required. Flashing must be done via a SOIC-8 PatchClamp or by soldering a socket
for the flash chip.
If you don't want to open your device, you can use the project's code to learn about the
devices by looking at the image using e.g. Ghidra. If you want to contribute to the
design of the web-interface or get a feeling for the interface first, a standalone
device simulator is provided, which runs entirely under Linux as a local webserver.
(0) Compiling Requirements
Install the following particular build requisites (Debian 12/13):
sudo apt install make gcc g++ pkg-config bison flex libboost-dev patch bzip2 curl xxd python-is-python3 libjson-c-dev zlib1g-dev
The first make downloads SDCC 4.6.0, applies the fixes in sdcc/ and builds it into
toolchain/, which takes a few minutes. Later builds reuse it. The released SDCC 4.5.0
and 4.6.0 miscompile parts of this code, see SDCC bug #4153
and #4154; both fixes are in SDCC trunk since
r17039. The third patch is for #4070, where the
assembler drops the top byte of a __sfr32 address list; it is proposed upstream and lets
SFR_DATA_U32 be used again. To use an SDCC you installed yourself instead, run make CC=sdcc ....
Prerequisites
Install Docker for your platform:
Usage
A Dockerfile is provided for a reproducible build environment:
docker build -t rtlplayground-dev .
Build the firmware (replace MACHINE with your target, e.g. DEFAULT_8C_1SFP):
docker run --rm -v $(pwd):/workspace rtlplayground-dev make MACHINE=DEFAULT_8C_1SFP
The resulting .bin file appears in output/ on your host.
Build the OEM web upgrade bin (after building the firmware bin)
docker run --rm -v $(pwd):/workspace rtlplayground-dev make -C installer
The resulting rtlplayground_oem_upgrade.bin file appears in installer/output/ on your host.
Build host tools only:
docker run --rm -v $(pwd):/workspace rtlplayground-dev make -C tools
Run the web-interface simulator through docker:
docker run --rm -p 8081:8081 -v $(pwd):/workspace rtlplayground-dev \
tools/output/httpd_sim.py /workspace/html
Edit config.txt on your host, then re-run make — the
source directory is mounted into the container, so changes take effect
immediately. To build for a different machine, pass MACHINE=<name>, which
selects machine/<name>.c (see Adding a new device).
This is the beginning of the README. Read the rest at the original. Read the full README ↗
