Merge tag 'u-boot-rockchip-20251214' of https://source.denx.de/u-boot/custodians/u-boot-rockchip

CI: https://source.denx.de/u-boot/custodians/u-boot-rockchip/-/pipelines/28748

Please pull the updates for rockchip platform:
- New Board support: rk3588 Radxa ROCK 5T, ROCK 5B+;
- I2C Fixes;
- RAM boot from maskrom;

24 files changed, 277 insertions, 52 deletions

diff --git a/arch/arm/dts/rk3588-rock-5b-plus-u-boot.dtsi b/arch/arm/dts/rk3588-rock-5b-plus-u-boot.dtsi
new file mode 100644
index 00000000000..c07696c8391
--- /dev/null
+++ b/arch/arm/dts/rk3588-rock-5b-plus-u-boot.dtsi
@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: (GPL-2.0+ OR MIT)
+
+#include "rk3588-rock-5b-u-boot.dtsi"
diff --git a/arch/arm/dts/rk3588-rock-5b-u-boot.dtsi b/arch/arm/dts/rk3588-rock-5b-u-boot.dtsi
index d51fbf51cb8..e07b549c767 100644
--- a/arch/arm/dts/rk3588-rock-5b-u-boot.dtsi
+++ b/arch/arm/dts/rk3588-rock-5b-u-boot.dtsi
@@ -46,6 +46,11 @@
 	};
 };
 
+&saradc {
+	bootph-pre-ram;
+	vdd-microvolts = <1800000>;
+};
+
 &sdhci {
 	cap-mmc-highspeed;
 	mmc-hs200-1_8v;
diff --git a/arch/arm/dts/rk3588-rock-5t-u-boot.dtsi b/arch/arm/dts/rk3588-rock-5t-u-boot.dtsi
new file mode 100644
index 00000000000..c07696c8391
--- /dev/null
+++ b/arch/arm/dts/rk3588-rock-5t-u-boot.dtsi
@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: (GPL-2.0+ OR MIT)
+
+#include "rk3588-rock-5b-u-boot.dtsi"
diff --git a/arch/arm/dts/rockchip-u-boot.dtsi b/arch/arm/dts/rockchip-u-boot.dtsi
index cc2feed6464..71d7623fe2c 100644
--- a/arch/arm/dts/rockchip-u-boot.dtsi
+++ b/arch/arm/dts/rockchip-u-boot.dtsi
@@ -226,5 +226,38 @@
 		};
 	};
 #endif /* CONFIG_ROCKCHIP_SPI_IMAGE */
+
+#ifdef CONFIG_ROCKCHIP_MASKROM_IMAGE
+	simple-bin-usb471 {
+		filename = "u-boot-rockchip-usb471.bin";
+
+#ifdef CONFIG_ROCKCHIP_EXTERNAL_TPL
+		rockchip-tpl {
+		};
+#elif defined(CONFIG_TPL)
+		u-boot-tpl {
+			no-write-symbols;
+		};
+#endif
+	};
+
+	simple-bin-usb472 {
+		filename = "u-boot-rockchip-usb472.bin";
+		pad-byte = <0x00>;
+
+		u-boot-spl {
+			no-write-symbols;
+		};
+
+#ifdef HAS_FIT
+		fit {
+			insert-template = <&fit_template>;
+#else
+		u-boot-img {
+#endif
+			offset = <(CONFIG_SPL_LOAD_FIT_ADDRESS - CFG_SYS_SDRAM_BASE)>;
+		};
+	};
+#endif /* CONFIG_ROCKCHIP_MASKROM_IMAGE */
 };
 #endif /* CONFIG_SPL */
diff --git a/arch/arm/include/asm/arch-rockchip/sdram.h b/arch/arm/include/asm/arch-rockchip/sdram.h
index 4fb45ac5c76..476fc1c4ee3 100644
--- a/arch/arm/include/asm/arch-rockchip/sdram.h
+++ b/arch/arm/include/asm/arch-rockchip/sdram.h
@@ -87,6 +87,9 @@ enum {
 #define SYS_REG_CS1_COL_SHIFT(ch)		(0 + (ch) * 2)
 #define SYS_REG_CS1_COL_MASK			3
 
+/* Get sdram type decode from reg */
+u8 rockchip_sdram_type(phys_addr_t reg);
+
 /* Get sdram size decode from reg */
 size_t rockchip_sdram_size(phys_addr_t reg);
 
diff --git a/arch/arm/mach-rockchip/Kconfig b/arch/arm/mach-rockchip/Kconfig
index 342933ca509..e32e49ff59a 100644
--- a/arch/arm/mach-rockchip/Kconfig
+++ b/arch/arm/mach-rockchip/Kconfig
@@ -706,6 +706,14 @@ config ROCKCHIP_SPI_IMAGE
 	  option to produce a SPI-flash image containing U-Boot. The image
 	  is built by binman. U-Boot sits near the start of the image.
 
+config ROCKCHIP_MASKROM_IMAGE
+	bool "Build a maskrom mode image for Rockchip"
+	depends on TPL || ROCKCHIP_EXTERNAL_TPL
+	select SPL_RAM_DEVICE
+	help
+	  Rockchip SoCs support maskrom mode boot over USB. Enable this
+	  option to produce maskrom mode boot images containing U-Boot.
+
 config LNX_KRNL_IMG_TEXT_OFFSET_BASE
 	default TEXT_BASE
 
@@ -768,9 +776,9 @@ config TPL_SYS_MALLOC_F_LEN
 	default 0x4000 if CUSTOM_SYS_INIT_SP_ADDR = 0x03f00000
 
 config TEXT_BASE
-	default 0x60200000 if SPL_TEXT_BASE = 0x60000000
-	default 0x40200000 if SPL_TEXT_BASE = 0x40000000
-	default 0x00200000 if SPL_TEXT_BASE = 0x00000000
+	default 0x60800000 if SPL_TEXT_BASE = 0x60000000
+	default 0x40800000 if SPL_TEXT_BASE = 0x40000000
+	default 0x00800000 if SPL_TEXT_BASE = 0x00000000
 
 config SPL_TEXT_BASE
 	default 0x60000000 if ROCKCHIP_RK3036 || ROCKCHIP_RK3066 || \
diff --git a/arch/arm/mach-rockchip/rk3308/Kconfig b/arch/arm/mach-rockchip/rk3308/Kconfig
index 06572d545f6..b8d25c52542 100644
--- a/arch/arm/mach-rockchip/rk3308/Kconfig
+++ b/arch/arm/mach-rockchip/rk3308/Kconfig
@@ -17,9 +17,6 @@ config ROCKCHIP_STIMER_BASE
 config SYS_SOC
 	default "rk3308"
 
-config TEXT_BASE
-	default 0x00600000
-
 source "board/rockchip/evb_rk3308/Kconfig"
 source "board/firefly/firefly-rk3308/Kconfig"
 
diff --git a/arch/arm/mach-rockchip/rk3568/Kconfig b/arch/arm/mach-rockchip/rk3568/Kconfig
index 01b53a47ddb..2730220a18e 100644
--- a/arch/arm/mach-rockchip/rk3568/Kconfig
+++ b/arch/arm/mach-rockchip/rk3568/Kconfig
@@ -70,9 +70,6 @@ config ROCKCHIP_STIMER_BASE
 config SYS_SOC
 	default "rk3568"
 
-config TEXT_BASE
-	default 0x00a00000
-
 source "board/rockchip/evb_rk3568/Kconfig"
 source "board/anbernic/rgxx3_rk3566/Kconfig"
 source "board/hardkernel/odroid_m1/Kconfig"
diff --git a/arch/arm/mach-rockchip/rk3588/Kconfig b/arch/arm/mach-rockchip/rk3588/Kconfig
index 9fbe3f225aa..60c16d2f32d 100644
--- a/arch/arm/mach-rockchip/rk3588/Kconfig
+++ b/arch/arm/mach-rockchip/rk3588/Kconfig
@@ -417,9 +417,6 @@ config ROCKCHIP_STIMER_BASE
 config SYS_SOC
 	default "rk3588"
 
-config TEXT_BASE
-	default 0x00a00000
-
 source "board/armsom/sige7-rk3588/Kconfig"
 source "board/coolpi/genbook_cm5_rk3588/Kconfig"
 source "board/edgeble/neural-compute-module-6/Kconfig"
diff --git a/arch/arm/mach-rockchip/sdram.c b/arch/arm/mach-rockchip/sdram.c
index 3bc482331c7..d560f90e873 100644
--- a/arch/arm/mach-rockchip/sdram.c
+++ b/arch/arm/mach-rockchip/sdram.c
@@ -345,6 +345,21 @@ int dram_init_banksize(void)
 	return 0;
 }
 
+u8 rockchip_sdram_type(phys_addr_t reg)
+{
+	u32 dram_type, version;
+	u32 sys_reg2 = readl(reg);
+	u32 sys_reg3 = readl(reg + 4);
+
+	dram_type = (sys_reg2 >> SYS_REG_DDRTYPE_SHIFT) & SYS_REG_DDRTYPE_MASK;
+	version = (sys_reg3 >> SYS_REG_VERSION_SHIFT) & SYS_REG_VERSION_MASK;
+	if (version >= 3)
+		dram_type |= ((sys_reg3 >> SYS_REG_EXTEND_DDRTYPE_SHIFT) &
+			      SYS_REG_EXTEND_DDRTYPE_MASK) << 3;
+
+	return dram_type;
+}
+
 size_t rockchip_sdram_size(phys_addr_t reg)
 {
 	u32 rank, cs0_col, bk, cs0_row, cs1_row, bw, row_3_4;
diff --git a/arch/arm/mach-rockchip/spl-boot-order.c b/arch/arm/mach-rockchip/spl-boot-order.c
index 1ea1033b5ea..6572dde29f6 100644
--- a/arch/arm/mach-rockchip/spl-boot-order.c
+++ b/arch/arm/mach-rockchip/spl-boot-order.c
@@ -8,6 +8,7 @@
 #include <log.h>
 #include <mmc.h>
 #include <spl.h>
+#include <asm/arch-rockchip/bootrom.h>
 #include <asm/global_data.h>
 #include <dm/uclass-internal.h>
 
@@ -98,15 +99,22 @@ __weak const char *board_spl_was_booted_from(void)
 
 void board_boot_order(u32 *spl_boot_list)
 {
+	int idx = 0;
+
+	/* Add RAM boot for maskrom mode boot over USB */
+	if (BROM_BOOTSOURCE_ID_ADDR && CONFIG_IS_ENABLED(RAM_DEVICE) &&
+	    read_brom_bootsource_id() == BROM_BOOTSOURCE_USB) {
+		spl_boot_list[idx++] = BOOT_DEVICE_RAM;
+	}
+
 	/* In case of no fdt (or only plat), use spl_boot_device() */
 	if (!CONFIG_IS_ENABLED(OF_CONTROL) || CONFIG_IS_ENABLED(OF_PLATDATA)) {
-		spl_boot_list[0] = spl_boot_device();
+		spl_boot_list[idx++] = spl_boot_device();
 		return;
 	}
 
 	const void *blob = gd->fdt_blob;
 	int chosen_node = fdt_path_offset(blob, "/chosen");
-	int idx = 0;
 	int elem;
 	int boot_device;
 	int node;
@@ -115,7 +123,7 @@ void board_boot_order(u32 *spl_boot_list)
 	if (chosen_node < 0) {
 		debug("%s: /chosen not found, using spl_boot_device()\n",
 		      __func__);
-		spl_boot_list[0] = spl_boot_device();
+		spl_boot_list[idx++] = spl_boot_device();
 		return;
 	}
 
diff --git a/board/radxa/rock5b-rk3588/Kconfig b/board/radxa/rock5b-rk3588/Kconfig
index 41dfe2402b1..98d63011783 100644
--- a/board/radxa/rock5b-rk3588/Kconfig
+++ b/board/radxa/rock5b-rk3588/Kconfig
@@ -9,4 +9,9 @@ config SYS_VENDOR
 config SYS_CONFIG_NAME
 	default "rock5b-rk3588"
 
+config BOARD_SPECIFIC_OPTIONS # dummy
+	def_bool y
+	select ADC
+	select SPL_ADC
+
 endif
diff --git a/board/radxa/rock5b-rk3588/MAINTAINERS b/board/radxa/rock5b-rk3588/MAINTAINERS
index 4460c9971a9..c8a43769105 100644
--- a/board/radxa/rock5b-rk3588/MAINTAINERS
+++ b/board/radxa/rock5b-rk3588/MAINTAINERS
@@ -5,5 +5,4 @@ S:	Maintained
 F:	board/radxa/rock5b-rk3588
 F:	include/configs/rock5b-rk3588.h
 F:	configs/rock5b-rk3588_defconfig
-F:	arch/arm/dts/rk3588-rock-5b.dts
-F:	arch/arm/dts/rk3588-rock-5b-u-boot.dtsi
+F:	arch/arm/dts/rk3588-rock-5b*
diff --git a/board/radxa/rock5b-rk3588/rock5b-rk3588.c b/board/radxa/rock5b-rk3588/rock5b-rk3588.c
index fc2f69db224..2c172d04499 100644
--- a/board/radxa/rock5b-rk3588/rock5b-rk3588.c
+++ b/board/radxa/rock5b-rk3588/rock5b-rk3588.c
@@ -3,8 +3,72 @@
  * Copyright (c) 2023-2024 Collabora Ltd.
  */
 
+#include <adc.h>
+#include <env.h>
 #include <fdtdec.h>
 #include <fdt_support.h>
+#include <asm/arch-rockchip/sdram.h>
+#include <linux/errno.h>
+
+#define PMU1GRF_BASE		0xfd58a000
+#define OS_REG2_REG		0x208
+
+#define HW_ID_CHANNEL		5
+
+struct board_model {
+	unsigned int dram;
+	unsigned int low;
+	unsigned int high;
+	const char *fdtfile;
+};
+
+static const struct board_model board_models[] = {
+	{ LPDDR5,  926, 1106, "rockchip/rk3588-rock-5t.dtb" },
+	{ LPDDR5, 4005, 4185, "rockchip/rk3588-rock-5b-plus.dtb" },
+};
+
+static const struct board_model *get_board_model(void)
+{
+	unsigned int val, dram_type;
+	int i, ret;
+
+	dram_type = rockchip_sdram_type(PMU1GRF_BASE + OS_REG2_REG);
+
+	ret = adc_channel_single_shot("adc@fec10000", HW_ID_CHANNEL, &val);
+	if (ret)
+		return NULL;
+
+	for (i = 0; i < ARRAY_SIZE(board_models); i++) {
+		unsigned int dram = board_models[i].dram;
+		unsigned int min = board_models[i].low;
+		unsigned int max = board_models[i].high;
+
+		if (dram == dram_type && min <= val && val <= max)
+			return &board_models[i];
+	}
+
+	return NULL;
+}
+
+int rk_board_late_init(void)
+{
+	const struct board_model *model = get_board_model();
+
+	if (model)
+		env_set("fdtfile", model->fdtfile);
+
+	return 0;
+}
+
+int board_fit_config_name_match(const char *name)
+{
+	const struct board_model *model = get_board_model();
+
+	if (model && !strcmp(name, model->fdtfile))
+		return 0;
+
+	return -EINVAL;
+}
 
 #ifdef CONFIG_OF_BOARD_SETUP
 int ft_board_setup(void *blob, struct bd_info *bd)
diff --git a/board/rockchip/rockchip-ramboot.config b/board/rockchip/rockchip-ramboot.config
new file mode 100644
index 00000000000..312363e542b
--- /dev/null
+++ b/board/rockchip/rockchip-ramboot.config
@@ -0,0 +1 @@
+CONFIG_ROCKCHIP_MASKROM_IMAGE=y
diff --git a/boot/Kconfig b/boot/Kconfig
index 85f4d468069..245e120c70b 100644
--- a/boot/Kconfig
+++ b/boot/Kconfig
@@ -275,6 +275,9 @@ config SPL_LOAD_FIT_ADDRESS
 	hex "load address of fit image"
 	depends on SPL_LOAD_FIT
 	default 0x44000000 if ARCH_IMX8M
+	default 0x60080000 if ARCH_ROCKCHIP && SPL_TEXT_BASE = 0x60000000
+	default 0x40200000 if ARCH_ROCKCHIP && SPL_TEXT_BASE = 0x40000000
+	default 0x00200000 if ARCH_ROCKCHIP && SPL_TEXT_BASE = 0x00000000
 	default 0x0
 	help
 	  Specify the load address of the fit image that will be loaded
diff --git a/configs/rock5b-rk3588_defconfig b/configs/rock5b-rk3588_defconfig
index 6349e879145..567f649ea69 100644
--- a/configs/rock5b-rk3588_defconfig
+++ b/configs/rock5b-rk3588_defconfig
@@ -47,6 +47,7 @@ CONFIG_CMD_REGULATOR=y
 # CONFIG_SPL_DOS_PARTITION is not set
 CONFIG_SPL_OF_CONTROL=y
 CONFIG_OF_LIVE=y
+CONFIG_OF_LIST="rockchip/rk3588-rock-5b rockchip/rk3588-rock-5b-plus rockchip/rk3588-rock-5t"
 CONFIG_OF_SPL_REMOVE_PROPS="clock-names interrupt-parent assigned-clocks assigned-clock-rates assigned-clock-parents"
 CONFIG_SPL_DM_SEQ_ALIAS=y
 CONFIG_SPL_REGMAP=y
diff --git a/doc/board/rockchip/rockchip.rst b/doc/board/rockchip/rockchip.rst
index 0acccb51ad5..6ae4d4371ff 100644
--- a/doc/board/rockchip/rockchip.rst
+++ b/doc/board/rockchip/rockchip.rst
@@ -162,7 +162,7 @@ List of mainline supported Rockchip boards:
      - Pine64 QuartzPro64 (quartzpro64-rk3588)
      - Radxa ROCK 5 ITX (rock-5-itx-rk3588)
      - Radxa ROCK 5A (rock5a-rk3588s)
-     - Radxa ROCK 5B (rock5b-rk3588)
+     - Radxa ROCK 5B/5B+/5T (rock5b-rk3588)
      - Radxa ROCK 5C (rock-5c-rk3588s)
      - Rockchip Toybrick TB-RK3588X (toybrick-rk3588)
      - Theobroma Systems RK3588-SBC Jaguar (jaguar-rk3588)
diff --git a/doc/board/theobroma-systems/jaguar_rk3588.rst b/doc/board/theobroma-systems/jaguar_rk3588.rst
index cba4fd066ab..d09cfaa88ff 100644
--- a/doc/board/theobroma-systems/jaguar_rk3588.rst
+++ b/doc/board/theobroma-systems/jaguar_rk3588.rst
@@ -32,24 +32,47 @@ It provides the following features:
 Here is the step-by-step to boot to U-Boot on SBC-RK3588-AMR Jaguar from Theobroma
 Systems.
 
-Get the TF-A and DDR init (TPL) binaries
-----------------------------------------
+Get DDR init (TPL) binary
+-------------------------
 
 .. prompt:: bash
 
    git clone https://github.com/rockchip-linux/rkbin
    cd rkbin
-   export RKBIN=$(pwd)
-   export BL31=$RKBIN/bin/rk35/rk3588_bl31_v1.47.elf
-   export ROCKCHIP_TPL=$RKBIN/bin/rk35/rk3588_ddr_lp4_2112MHz_lp5_2400MHz_v1.18.bin
+   export ROCKCHIP_TPL=$(readlink -f bin/rk35/rk3588_ddr_lp4_2112MHz_lp5_2400MHz_v*.bin | head -1)
    sed -i 's/^uart baudrate=.*$/uart baudrate=115200/' tools/ddrbin_param.txt
-   ./tools/ddrbin_tool rk3588 tools/ddrbin_param.txt "$ROCKCHIP_TPL"
+   sed -i 's/^uart iomux=.*$/uart iomux=0/' tools/ddrbin_param.txt
+   python3 ./tools/ddrbin_tool.py rk3588 tools/ddrbin_param.txt "$ROCKCHIP_TPL"
    ./tools/boot_merger RKBOOT/RK3588MINIALL.ini
-   export RKDB=$RKBIN/rk3588_spl_loader_v1.11.112.bin
+   export RKDB=$(readlink -f rk3588_spl_loader_v*.bin | head -1)
 
 This will setup all required external dependencies for compiling U-Boot. This will
-be updated in the future once upstream Trusted-Firmware-A supports RK3588 or U-Boot
-gains support for open-source DRAM initialization in TPL.
+be updated in the future once U-Boot gains support for open-source DRAM initialization
+in TPL.
+
+Get TF-A
+--------
+
+There are two possible options, pick one or the other. Note that the instructions need
+to be run from the ``rkbin`` directory.
+
+Prebuilt binary from Rockchip
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. prompt:: bash
+
+   export BL31=$(readlink -f bin/rk35/rk3588_bl31_v*.elf | head -1)
+
+Upstream
+~~~~~~~~
+
+.. prompt:: bash
+
+   cd ../
+   git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
+   cd trusted-firmware-a
+   make CROSS_COMPILE=aarch64-linux-gnu- PLAT=rk3588 bl31
+   export BL31=$PWD/build/rk3588/release/bl31/bl31.elf
 
 Build U-Boot
 ------------
@@ -59,6 +82,11 @@ Build U-Boot
    cd ../u-boot
    make CROSS_COMPILE=aarch64-linux-gnu- jaguar-rk3588_defconfig all
 
+.. note::
+   If using upstream TF-A, one should disable ``SPL_ATF_NO_PLATFORM_PARAM`` symbol in
+   U-Boot config (via e.g. ``make CROSS_COMPILE=aarch64-linux-gnu- menuconfig``) which
+   will, among other things, enable console output in TF-A.
+
 This will build ``u-boot-rockchip.bin`` which can be written to an MMC device
 (eMMC or SD card).
 
diff --git a/doc/board/theobroma-systems/puma_rk3399.rst b/doc/board/theobroma-systems/puma_rk3399.rst
index a2a5e7bca4b..1a8d33f188d 100644
--- a/doc/board/theobroma-systems/puma_rk3399.rst
+++ b/doc/board/theobroma-systems/puma_rk3399.rst
@@ -95,8 +95,9 @@ To flash U-Boot on the eMMC with ``rkdeveloptool``:
    git clone https://github.com/rockchip-linux/rkbin.git
    cd rkbin
    ./tools/boot_merger RKBOOT/RK3399MINIALL.ini
+   export RKDB=$(readlink -f rk3399_loader_v*.bin | head -1)
    cd ..
-   ./rkdeveloptool db rkbin/rk3399_loader_v1.30.130.bin
+   ./rkdeveloptool db "$RKDB"
    ./rkdeveloptool wl 64 ../u-boot-rockchip.bin
 
 NOR-Flash
@@ -121,7 +122,8 @@ To flash U-Boot on the SPI with ``rkdeveloptool``:
    git clone https://github.com/rockchip-linux/rkbin.git
    cd rkbin
    ./tools/boot_merger RKBOOT/RK3399MINIALL_SPINOR.ini
+   export RKDB=$(readlink -f rk3399_loader_spinor_v*.bin | head -1)
    cd ..
-   ./rkdeveloptool db rkbin/rk3399_loader_spinor_v1.30.114.bin
+   ./rkdeveloptool db "$RKDB"
    ./rkdeveloptool ef
    ./rkdeveloptool wl 0 ../u-boot-rockchip-spi.bin
diff --git a/doc/board/theobroma-systems/ringneck_px30.rst b/doc/board/theobroma-systems/ringneck_px30.rst
index c16b9ed17ed..d3feedf6062 100644
--- a/doc/board/theobroma-systems/ringneck_px30.rst
+++ b/doc/board/theobroma-systems/ringneck_px30.rst
@@ -90,6 +90,7 @@ To flash U-Boot on the eMMC with ``rkdeveloptool``:
    git clone https://github.com/rockchip-linux/rkbin.git
    cd rkbin
    ./tools/boot_merger RKBOOT/PX30MINIALL.ini
+   export RKDB=$(readlink -f px30_loader_v*.bin | head -1)
    cd ..
-   ./rkdeveloptool db rkbin/px30_loader_v2.08.135.bin
+   ./rkdeveloptool db "$RKDB"
    ./rkdeveloptool wl 64 ../u-boot-rockchip.bin
diff --git a/doc/board/theobroma-systems/tiger_rk3588.rst b/doc/board/theobroma-systems/tiger_rk3588.rst
index 4586b8d8b5a..493f191020f 100644
--- a/doc/board/theobroma-systems/tiger_rk3588.rst
+++ b/doc/board/theobroma-systems/tiger_rk3588.rst
@@ -39,25 +39,47 @@ It provides the following feature set:
 Here is the step-by-step to boot to U-Boot on SOM-RK3588-Q7 Tiger from Theobroma
 Systems.
 
-Get the TF-A and DDR init (TPL) binaries
-----------------------------------------
+Get DDR init (TPL) binary
+-------------------------
 
 .. prompt:: bash
 
    git clone https://github.com/rockchip-linux/rkbin
    cd rkbin
-   export RKBIN=$(pwd)
-   export BL31=$RKBIN/bin/rk35/rk3588_bl31_v1.47.elf
-   export ROCKCHIP_TPL=$RKBIN/bin/rk35/rk3588_ddr_lp4_2112MHz_lp5_2400MHz_v1.18.bin
+   export ROCKCHIP_TPL=$(readlink -f bin/rk35/rk3588_ddr_lp4_2112MHz_lp5_2400MHz_v*.bin | head -1)
    sed -i 's/^uart baudrate=.*$/uart baudrate=115200/' tools/ddrbin_param.txt
    sed -i 's/^uart iomux=.*$/uart iomux=2/' tools/ddrbin_param.txt
-   ./tools/ddrbin_tool rk3588 tools/ddrbin_param.txt "$ROCKCHIP_TPL"
+   python3 ./tools/ddrbin_tool.py rk3588 tools/ddrbin_param.txt "$ROCKCHIP_TPL"
    ./tools/boot_merger RKBOOT/RK3588MINIALL.ini
-   export RKDB=$RKBIN/rk3588_spl_loader_v1.11.112.bin
+   export RKDB=$(readlink -f rk3588_spl_loader_v*.bin | head -1)
 
 This will setup all required external dependencies for compiling U-Boot. This will
-be updated in the future once upstream Trusted-Firmware-A supports RK3588 or U-Boot
-gains support for open-source DRAM initialization in TPL.
+be updated in the future once U-Boot gains support for open-source DRAM initialization
+in TPL.
+
+Get TF-A
+--------
+
+There are two possible options, pick one or the other. Note that the instructions need
+to be run from the ``rkbin`` directory.
+
+Prebuilt binary from Rockchip
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. prompt:: bash
+
+   export BL31=$(readlink -f bin/rk35/rk3588_bl31_v*.elf | head -1)
+
+Upstream
+~~~~~~~~
+
+.. prompt:: bash
+
+   cd ../
+   git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
+   cd trusted-firmware-a
+   make CROSS_COMPILE=aarch64-linux-gnu- PLAT=rk3588 bl31
+   export BL31=$PWD/build/rk3588/release/bl31/bl31.elf
 
 Build U-Boot
 ------------
@@ -67,6 +89,11 @@ Build U-Boot
    cd ../u-boot
    make CROSS_COMPILE=aarch64-linux-gnu- tiger-rk3588_defconfig all
 
+.. note::
+   If using upstream TF-A, one should disable ``SPL_ATF_NO_PLATFORM_PARAM`` symbol in
+   U-Boot config (via e.g. ``make CROSS_COMPILE=aarch64-linux-gnu- menuconfig``) which
+   will, among other things, enable console output in TF-A.
+
 This will build ``u-boot-rockchip.bin`` which can be written to an MMC device
 (eMMC or SD card).
 
diff --git a/drivers/i2c/rk_i2c.c b/drivers/i2c/rk_i2c.c
index fa167268ae7..def07018148 100644
--- a/drivers/i2c/rk_i2c.c
+++ b/drivers/i2c/rk_i2c.c
@@ -137,7 +137,7 @@ static int rk_i2c_send_stop_bit(struct rk_i2c *i2c)
 	writel(I2C_IPD_ALL_CLEAN, &regs->ipd);
 
 	writel(I2C_CON_EN | I2C_CON_STOP, &regs->con);
-	writel(I2C_CON_STOP, &regs->ien);
+	writel(I2C_STOPIEN, &regs->ien);
 
 	start = get_timer(0);
 	while (1) {
@@ -195,13 +195,14 @@ static int rk_i2c_read(struct rk_i2c *i2c, uchar chip, uint reg, uint r_len,
 
 	while (bytes_remain_len) {
 		if (bytes_remain_len > RK_I2C_FIFO_SIZE) {
-			con = I2C_CON_EN;
-			bytes_xferred = 32;
-		} else {
 			/*
 			 * The hw can read up to 32 bytes at a time. If we need
-			 * more than one chunk, send an ACK after the last byte.
+			 * more than one chunk, send an ACK after the last byte
+			 * of the current chunk.
 			 */
+			con = I2C_CON_EN;
+			bytes_xferred = 32;
+		} else {
 			con = I2C_CON_EN | I2C_CON_LASTACK;
 			bytes_xferred = bytes_remain_len;
 		}
@@ -254,8 +255,6 @@ static int rk_i2c_read(struct rk_i2c *i2c, uchar chip, uint reg, uint r_len,
 	}
 
 i2c_exit:
-	rk_i2c_disable(i2c);
-
 	return err;
 }
 
@@ -332,8 +331,6 @@ static int rk_i2c_write(struct rk_i2c *i2c, uchar chip, uint reg, uint r_len,
 	}
 
 i2c_exit:
-	rk_i2c_disable(i2c);
-
 	return err;
 }
 
@@ -358,6 +355,18 @@ static int rockchip_i2c_xfer(struct udevice *bus, struct i2c_msg *msg,
 			ret = -EREMOTEIO;
 			break;
 		}
+
+		/*
+		 * The HW is actually not capable of REPEATED START. But we can
+		 * get the intended effect by resetting its internal state
+		 * and issuing an ordinary START.
+		 *
+		 * Do NOT disable the controller after the last message (before
+		 * sending the STOP condition) as this triggers an illegal
+		 * START condition followed by a STOP condition.
+		 */
+		if (nmsgs > 1)
+			rk_i2c_disable(i2c);
 	}
 
 	rk_i2c_send_stop_bit(i2c);
diff --git a/tools/rkcommon.c b/tools/rkcommon.c
index d191ea72c63..e7e78ef7e5b 100644
--- a/tools/rkcommon.c
+++ b/tools/rkcommon.c
@@ -76,13 +76,29 @@ struct header0_info_v2 {
 /**
  * struct header0_info - header block for boot ROM
  *
- * This is stored at SD card block 64 (where each block is 512 bytes, or at
- * the start of SPI flash. It is encoded with RC4.
+ * This is stored at MMC block 64 (where each block is 512 bytes), or at
+ * the start of SPI flash. It is encoded with RC4 with the below rc4_key.
+ *
+ * In Rockchip terminology:
+ *
+ * "init" means the stage that is loaded into SRAM. TPL if there is one, SPL
+ * otherwise.
+ *
+ * "boot" means the next stages after "init" stage that are loaded by the
+ * BootROM into DRAM. Only applicable if "init" stage returns to BootROM (via
+ * the appropriate ROCKCHIP_BACK_TO_BROM symbol, BOOT_DEVICE_BOOTROM is used as
+ * boot device for the next stage and the "init" stage successfully booted) and
+ * if "init_boot_size" > "init_size".
+ * Basically, it is the content of "init" plus the SPL or even U-Boot proper if
+ * relevant.
  *
  * @magic:		Magic (must be RK_MAGIC)
  * @disable_rc4:	0 to use rc4 for boot image,  1 to use plain binary
- * @init_offset:	Offset in blocks of the SPL code from this header
- *			block. E.g. 4 means 2KB after the start of this header.
+ * @init_offset:	Offset in 512-byte blocks of the "init" code from the
+ *			start of this header. For instance, 4 means 2KiB.
+ * @init_size:		Size (in blocks) of the "init" code.
+ * @init_boot_size:	Size (in blocks) of the "init" and "boot" code combined.
+ *
  * Other fields are not used by U-Boot
  */
 struct header0_info {