You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -36,9 +61,18 @@ This repository contains an UEFI firmware implementation based on EDK2 for vario
36
61
> ACPI support is only being developed and tested against Windows. There are no plans to further improve functionality for other OSes. Consider using Device Tree instead (where applicable, for instance Linux).
37
62
38
63
## In Device Tree mode
64
+
### Vendor compatibility mode
65
+
| OS | Version | Tested/supported hardware | Notes |
66
+
| --- | --- | --- | --- |
67
+
| Rockchip SDK Linux | Kernel 5.10/6.1<br> Tested with:<br> - [Armbian rk3588-live-iso](https://github.com/amazingfate/rk3588-live-iso)| Platform-dependent, most peripherals work. | If using a different kernel, see [Device Tree configuration](#device-tree-configuration). |
68
+
69
+
### Mainline compatibility mode
39
70
| OS | Version | Tested/supported hardware | Notes |
40
71
| --- | --- | --- | --- |
41
-
| Rockchip SDK Linux | 5.10 legacy, tested with [Armbian rk3588-live-iso](https://github.com/amazingfate/rk3588-live-iso)| Platform-dependent, most peripherals work. | If using a different kernel, see [Device Tree configuration](#device-tree-configuration). |
72
+
| Generic upstream Linux | Kernel 6.10 or newer.<br> Tested with:<br> - Ubuntu 24.10<br> - Fedora Workstation 41 | Platform and kernel version dependent, see [Collabora's RK3588 upstream status](https://gitlab.collabora.com/hardware-enablement/rockchip-3588/notes-for-rockchip-3588/-/blob/main/mainline-status.md). | * Kernels older than 6.13 lack HDMI output. To work around this, see: [Device Tree configuration](#device-tree-configuration). |
73
+
74
+
> [!NOTE]
75
+
> Mainline support is only available on [Platinum](#platinum) platforms.
42
76
43
77
# Supported peripherals in UEFI
44
78
@@ -49,29 +83,24 @@ This repository contains an UEFI firmware implementation based on EDK2 for vario
49
83
50
84
| Device | Status | Notes |
51
85
| --- | --- | --- |
52
-
| USB 3 / 2.0 / 1.1 | 🟢 Working | Host-mode only, USB 3 devices connected to a Type-C port only work in one orientation. |
53
-
| PCIe 3.0 (RK3588) | 🟢 Working | No bifurcation support |
54
-
| PCIe 2.1 | 🟢 Working ||
55
-
| SATA | 🟢 Working ||
56
-
| SD/eMMC | 🟢 Working ||
57
-
| HDMI output | 🟡 Partial | Single display with mode limited at 1080p 60 Hz |
58
-
| DisplayPort output (USB-C) | 🟡 Partial | Mode fixed at 1080p 60 Hz, only works in one orientation of the Type-C port. Some displays may not work regardless. |
59
-
| eDP output | 🟡 Partial | Disabled, requires manual configuration depending on the platform and panel. |
60
-
| DSI output | 🟢 Working | Only enabled on Fydetab Duo. Requires manual configuration depending on the platform and panel. |
61
-
| GMAC Ethernet | 🔴 Not working | Only brought-up for OS usage |
62
-
| Realtek PCIe Ethernet | 🟢 Working | Some platforms don't have MAC addresses set, networking may not work in that case. |
63
-
| UART | 🟢 Working | UART2 console available at 1500000 baud rate |
64
-
| GPIO | 🟡 Partial | Only read, write and alt function supported |
65
-
| I2C | 🟢 Working ||
66
-
| SPI | 🟢 Working ||
67
-
| PWM | 🟢 Working ||
68
-
| SPI NOR Flash | 🟢 Working ||
69
-
| HYM8563 real-time clock | 🟢 Working ||
70
-
| RNG | 🟢 Working ||
71
-
| Cooling fan | 🟢 Working | Supported on most platforms. Fan connector where present, otherwise available at the GPIO header for 3-pin PWM fans (do *not* connect 2-pin fans there!):<br>* Orange Pi 5: `GPIO4_B2`<br>* Indiedroid Nova: `GPIO4_B4`|
72
-
| Status LED | 🟢 Working ||
73
-
| Voltage regulators (RK806, RK860) | 🟢 Working ||
74
-
| FUSB302 USB Type-C Controller | 🔴 Not working | Required for PD negotiation and connector orientation switching |
86
+
| USB 3 / 2.0 / 1.1 | 🟢 Working | Host-mode only, USB 3 devices connected to a Type-C port only work in one orientation. |
87
+
| PCIe 3.0 / 2.1 | 🟢 Working ||
88
+
| SATA | 🟢 Working ||
89
+
| SD/eMMC | 🟢 Working ||
90
+
| HDMI output | 🟡 Partial | Single display with mode limited at 1080p 60 Hz |
91
+
| DisplayPort output (USB-C) | 🟡 Partial | Mode fixed at 1080p 60 Hz, only works in one orientation of the Type-C port. Some displays may not work regardless. |
92
+
| eDP output | 🟡 Partial | Disabled, requires manual configuration depending on the platform and panel. |
93
+
| DSI output | 🟢 Working | Only enabled on Fydetab Duo. Requires manual configuration depending on the platform and panel. |
94
+
| GMAC Ethernet | 🔴 Not working | Only brought-up for OS usage |
95
+
| Realtek PCIe Ethernet | 🟢 Working | Some platforms don't have MAC addresses set, networking may not work in that case. |
96
+
| Low-speed (GPIO/UART/I2C/SPI/PWM) | 🟢 Working | UART2 console available at 1500000 baud rate |
97
+
| SPI NOR Flash | 🟢 Working ||
98
+
| HYM8563 real-time clock | 🟢 Working ||
99
+
| RNG | 🟢 Working ||
100
+
| Cooling fan | 🟢 Working | Supported on most platforms. Fan connector where present, otherwise available at the GPIO header for 3-pin PWM fans (do *not* connect 2-pin fans there!):<br>* Orange Pi 5: `GPIO4_B2`<br>* Indiedroid Nova: `GPIO4_B4`|
101
+
| Status LED | 🟢 Working ||
102
+
| Voltage regulators (RK806/RK860) | 🟢 Working ||
103
+
| FUSB302 USB Type-C Controller | 🔴 Not working | Required for PD negotiation and connector orientation switching |
75
104
76
105
# Getting started
77
106
## 1. Requirements
@@ -86,10 +115,10 @@ This repository contains an UEFI firmware implementation based on EDK2 for vario
86
115
## 2. Download the firmware image
87
116
The latest version can be obtained from <https://github.com/edk2-porting/edk2-rk3588/releases>.
88
117
89
-
If your platform is not yet supported, using an image meant for another device is **not** recommended. Although they are generally similar, voltage setup can happen to be different and you may risk damaging the board. External peripherals are unlikely to work either.
118
+
If your platform is not yet supported, using an image meant for another device is **NOT** recommended. Although they are generally similar, voltage setup can happen to be different and you may risk damaging the board. External peripherals are unlikely to work either.
90
119
91
120
## 3. Flash the firmware
92
-
UEFI can be flashed to either a SPI NOR flash, SD card or eMMC module:
121
+
UEFI can be flashed to either an SPI NOR flash, SD card or eMMC module:
93
122
* For removable SD or eMMC (easiest), you can simply use balenaEtcher, RPi Imager or dd.
94
123
* For SPI NOR or soldered eMMC, instructions can be found at: <https://wiki.radxa.com/Rock5/install/spi>.
95
124
@@ -123,12 +152,21 @@ Configuration through the user interface is fairly straightforward and help/navi
123
152
## Device Tree configuration
124
153
For rich Linux support, it is recommended to enable Device Tree mode. You can do so by going to the configuration menu -> `ACPI / Device Tree` and setting `Config Table Mode` to `Device Tree`.
125
154
126
-
By default, the firmware installs a [DTB compatible with (most) Rockchip SDK Linux 5.10 legacy kernel variants](https://github.com/edk2-porting/edk2-rk3588/tree/master/edk2-rockchip-non-osi/Platform/Rockchip/DeviceTree).
155
+
The firmware provides two compatibility modes:
156
+
*`Vendor` - compatible with Rockchip SDK Linux 5.10/6.1 kernel only.
157
+
*`Mainline` - compatible with generic upstream Linux 6.10 or newer kernel. This option is under active development and may lack certain features. Therefore, it is always recommended to use the latest kernel and firmware available in order to benefit from better device support.
158
+
159
+
[Platinum](#platinum) platforms will have the `Mainline` option enabled by default, while [Bronze](#bronze) ones will fall back to `Vendor`.
160
+
161
+
> [!TIP]
162
+
> In `Mainline` mode with generic Linux kernels older than 6.13, the HDMI output will not be usable. To use the UEFI-initialized display instead, go to the configuration menu -> `ACPI / Device Tree` and enable `Force UEFI GOP Display`. Note that GPU acceleration cannot work in this mode.
127
163
128
164
### Custom Device Tree Blob (DTB) override and overlays
129
165
It is also possible to provide a custom DTB and overlays. To enable this, go to the configuration menu -> `ACPI / Device Tree` and set `Support DTB override & overlays` to `Enabled`.
130
166
131
-
The firmware will now look for overrides in the partition of a selected boot option / OS loader. In most cases this will be the first FAT32 EFI System Partition.
167
+
The firmware will now look for overrides in the partition of a selected boot option / OS loader. In most cases, this will be the first FAT32 EFI System Partition.
168
+
169
+
**Important:** The `dtb` directory must be placed at the root of the partition. It should not be inside any sub-directory.
132
170
133
171
* The base DTB must be located at `\dtb\base\<PLATFORM-DT-NAME>.dtb`.
134
172
@@ -138,19 +176,19 @@ The firmware will now look for overrides in the partition of a selected boot opt
138
176
139
177
and must have the `.dtbo` extension.
140
178
141
-
The paths above are relative to the root of the file system. That is, the `dtb` directory must not be placed in a sub-directory.
@@ -193,7 +231,7 @@ Here we skip the GPT and copy the firmware starting at offset 0x8000 (`64` block
193
231
> [!IMPORTANT]
194
232
> First of all, make sure your device can only possibly load the UEFI firmware and nothing else.
195
233
>
196
-
> **U-Boot must not present on either SPI NOR, SD or eMMC, otherwise it could take precedence and cause hidden issues.**
234
+
> **U-Boot must not be present on either SPI NOR, SD or eMMC, otherwise it could take precedence and cause issues.**
197
235
198
236
Below you can find some basic debugging information. If none of this helps, please see the [Advanced troubleshooting](#advanced-troubleshooting) section.
199
237
@@ -212,6 +250,11 @@ If the LED:
212
250
213
251
Note that it is only expected to stop as described at point 3) above.
214
252
253
+
## Recovery
254
+
In case you don't have easy access to the MaskROM button, UEFI provides a boot option for that purpose, accessible either via the Boot Manager or <kbd>F4</kbd> key during splash screen.
255
+
256
+
Additionally, holding the Recovery (or volume up) button while powering on the device will also enter MaskROM mode.
257
+
215
258
## Common issues
216
259
### Nothing shows up on the screen
217
260
Make sure you've flashed the firmware correctly and that it is the version designed for your device. In most cases this is the culprit.
@@ -224,13 +267,7 @@ Assuming the firmware loads fine:
224
267
If you are not able to get any display output, the only way to interact with UEFI is via the [serial console](#advanced-troubleshooting).
225
268
226
269
### Configuration settings do not get saved
227
-
This has been observed in cases where U-Boot was still present on another boot device (SD, eMMC or SPI NOR). This is not a supported scenario. The solution is to unplug or erase devices that may have other firmware on them.
228
-
229
-
What's happening:
230
-
1. Board loads U-Boot from a storage device that has higher priority (let's say eMMC).
231
-
2. That U-Boot image in turn loads UEFI and its settings from another device with lower priority (let's say SD).
232
-
3. UEFI cannot accurately determine to which device it belongs. The parameter used to verify this points to eMMC (U-Boot), while UEFI actually got loaded from SD.
233
-
4. Consequently, UEFI mistakenly saves the user settings to eMMC. On reboot, U-Boot loads UEFI and the original/unchanged settings from SD and the cycle repeats.
270
+
This has been observed in cases where firmware was present on more than one device (SPI NOR, eMMC or SD). This is not a supported scenario, because UEFI will be unable to accurately determine the boot device it belongs to. The solution is to unplug or erase devices that may have other firmware on them.
234
271
235
272
### USB 3 devices do not work
236
273
* Try a different port.
@@ -361,11 +398,7 @@ The firmware expects these exact offsets, do not change them.
361
398
## Licenses
362
399
Most of the UEFI code is licensed under the default EDK2 license, which is [BSD-2-Clause-Patent](https://github.com/tianocore/edk2/blob/master/License.txt).
363
400
364
-
Some non-critical components have been ported from Rockchip's U-Boot fork and are licensed as **GPL-2.0-or-later**:
365
-
* UsbDpPhy
366
-
* DwDpLib
367
-
368
-
The files in `edk2-rockchip-non-osi` are licensed as **GPL-2.0-only**.
401
+
Some components ported from Linux and Rockchip's U-Boot fork are licensed as **GPL-2.0** (check `SPDX-License-Identifier`).
369
402
370
403
The license for some of the blobs in the `misc/rkbin/` directory can be found at: <https://github.com/rockchip-linux/rkbin/blob/master/LICENSE>. Note that it also contains binaries built from open-source projects such as U-Boot (SPL), Arm Trusted Firmware and OP-TEE, having a different license.
0 commit comments