From 54bef11a6cdf082ae23c7fbb133d56066b108538 Mon Sep 17 00:00:00 2001
From: Antoine van Gelder <antoine@greatscottgadgets.com>
Date: Mon, 17 Aug 2026 11:10:53 +0200
Subject: [PATCH 01/11] firmware: output '.m0_text' to its named region before
 appending to 'rom'

---
 firmware/common/LPC43xx_M4_M0_image_from_text.ld | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/firmware/common/LPC43xx_M4_M0_image_from_text.ld b/firmware/common/LPC43xx_M4_M0_image_from_text.ld
index a2dfed68f..c04c158d8 100644
--- a/firmware/common/LPC43xx_M4_M0_image_from_text.ld
+++ b/firmware/common/LPC43xx_M4_M0_image_from_text.ld
@@ -23,9 +23,11 @@
 SECTIONS
 {
 	.m0_text : {
-		PROVIDE(__m0_start__ = .);
+		. = ALIGN(4);
 		KEEP(*(.m0_bin*));
 		. = ALIGN(4);
-		PROVIDE(__m0_end__ = .);
-	} >rom
+	} >ram_m0 AT >rom
+
+	PROVIDE(__m0_start__ = LOADADDR(.m0_text));
+	PROVIDE(__m0_end__ = LOADADDR(.m0_text) + SIZEOF(.m0_text));
 }

From 57d4bcfa41edfeb63a2ed7805e5608dd954fa35a Mon Sep 17 00:00:00 2001
From: Antoine van Gelder <antoine@greatscottgadgets.com>
Date: Fri, 14 Aug 2026 10:51:51 +0200
Subject: [PATCH 02/11] firmware: add size checks for linker sections that are
 merged into 'rom'

---
 firmware/common/LPC4320_M4_memory.ld | 5 +++++
 firmware/common/LPC4330_M4_memory.ld | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/firmware/common/LPC4320_M4_memory.ld b/firmware/common/LPC4320_M4_memory.ld
index 48be94da2..2f3a46562 100644
--- a/firmware/common/LPC4320_M4_memory.ld
+++ b/firmware/common/LPC4320_M4_memory.ld
@@ -32,4 +32,9 @@ MEMORY
 	ram_sleep (rwx) : ORIGIN = 0x10088000, LENGTH = 8K
 }
 
+ASSERT(
+	SIZEOF(.text) + SIZEOF(.init_array) + SIZEOF(.ARM.exidx) <= 64K,
+	"Error: region `ram_local1' exceeds 64 kB."
+)
+
 INCLUDE LPC43xx_M4_memory.ld
diff --git a/firmware/common/LPC4330_M4_memory.ld b/firmware/common/LPC4330_M4_memory.ld
index 1d42ebee9..23de05cb1 100644
--- a/firmware/common/LPC4330_M4_memory.ld
+++ b/firmware/common/LPC4330_M4_memory.ld
@@ -32,4 +32,9 @@ MEMORY
 	ram_sleep (rwx) : ORIGIN = 0x10090000, LENGTH = 8K
 }
 
+ASSERT(
+	SIZEOF(.text) + SIZEOF(.init_array) + SIZEOF(.ARM.exidx) <= 96K,
+	"Error: region `ram_local1' exceeds 96 kB."
+)
+
 INCLUDE LPC43xx_M4_memory.ld

From 20c6c929040f99d81b9c8398ca0ac958588881df Mon Sep 17 00:00:00 2001
From: Antoine van Gelder <antoine@greatscottgadgets.com>
Date: Tue, 11 Aug 2026 17:53:55 +0200
Subject: [PATCH 03/11] firmware: split ram_local2 to create ram_rtconfig

---
 firmware/common/LPC4320_M4_memory.ld   | 32 ++++++++++++++++++----
 firmware/common/LPC4330_M4_memory.ld   | 34 +++++++++++++++++++----
 firmware/common/LPC43xx_M4_memory.ld   | 37 ++++++++++++++++++--------
 firmware/common/LPC43xx_M4_rtconfig.ld | 32 ++++++++++++++++++++++
 firmware/hackrf-common.cmake           |  4 +--
 firmware/hackrf_usb/hackrf_usb.c       | 20 ++++++++++++++
 6 files changed, 136 insertions(+), 23 deletions(-)
 create mode 100644 firmware/common/LPC43xx_M4_rtconfig.ld

diff --git a/firmware/common/LPC4320_M4_memory.ld b/firmware/common/LPC4320_M4_memory.ld
index 2f3a46562..984a4e637 100644
--- a/firmware/common/LPC4320_M4_memory.ld
+++ b/firmware/common/LPC4320_M4_memory.ld
@@ -24,12 +24,34 @@
 
 MEMORY
 {
+	/* UM10503 Rev. 2.5, 10 September 2019
+	 *   - Section 3.3.1  Table 10, LPC43xx/LPC43Sxx SRAM configuration
+	 *   - Section 3.3.3  On-chip flash
+	 *   - Section 3.3.5  Memory retention in the Power-down modes
+	 *   - Section 3.4    Figure 8, Flashless parts: Memory map with peripherals
+	 * LPC4350/30/20/10 Product data sheet Rev. 4.6, 14 March 2016
+	 *   - Section 7.17   Figure 7, LPC4350/30/20/10 Memory mapping (overview)
+	 */
+
+	/* - 0x0000 0000 : 256 MB shadow area ---------------------------------- */
 	/* rom is really the shadow region that points to SPI flash or elsewhere */
-	rom (rx)  : ORIGIN = 0x00000000, LENGTH =  1M
-	ram_local1 (rwx) : ORIGIN = 0x10000000, LENGTH =  64K
-	ram_usb (rw) : ORIGIN = 0x10010000, LENGTH = 32K
-	ram_local2 (rwx) : ORIGIN = 0x10080000, LENGTH =  32K
-	ram_sleep (rwx) : ORIGIN = 0x10088000, LENGTH = 8K
+	rom          (rx)  : ORIGIN = 0x00000000, LENGTH =  1M
+
+	/* - 0x1000 0000 : 96 kB local SRAM ------------------------------------ */
+	ram_local1   (rwx) : ORIGIN = 0x10000000, LENGTH = 64K
+	ram_usb      (rw)  : ORIGIN = 0x10010000, LENGTH = 32K
+
+	/* - 0x1001 8000 : 32 kB local SRAM (LPC4350/30) ----------------------- */
+	/* - 0x1002 0000 : reserved -------------------------------------------- */
+
+	/* - 0x1008 0000 : 32 kB local SRAM (LPC4350/30/20/10) ----------------- */
+	ram_rtconfig (rx)  : ORIGIN = 0x10080000, LENGTH = 16K
+	ram_local2   (rwx) : ORIGIN = 0x10084000, LENGTH = 16K
+
+	/* - 0x1008 8000: 8 kB local SRAM (LPC4320/10) ------------------------- */
+	ram_sleep    (rwx) : ORIGIN = 0x10088000, LENGTH =  8K
+
+	/* - 0x1008 A000 : 32 kB local SRAM (LPC4350/30) ----------------------- */
 }
 
 ASSERT(
diff --git a/firmware/common/LPC4330_M4_memory.ld b/firmware/common/LPC4330_M4_memory.ld
index 23de05cb1..60df2dbea 100644
--- a/firmware/common/LPC4330_M4_memory.ld
+++ b/firmware/common/LPC4330_M4_memory.ld
@@ -24,12 +24,36 @@
 
 MEMORY
 {
+	/* UM10503 Rev. 2.5, 10 September 2019
+	 *   - Section 3.3.1  Table 10, LPC43xx/LPC43Sxx SRAM configuration
+	 *   - Section 3.3.3  On-chip flash
+	 *   - Section 3.3.5  Memory retention in the Power-down modes
+	 *   - Section 3.4    Figure 8, Flashless parts: Memory map with peripherals
+	 * LPC4350/30/20/10 Product data sheet Rev. 4.6, 14 March 2016
+	 *   - Section 7.17   Figure 7, LPC4350/30/20/10 Memory mapping (overview)
+	 */
+
+	/* - 0x0000 0000 : 256 MB shadow area ---------------------------------- */
+
 	/* rom is really the shadow region that points to SPI flash or elsewhere */
-	rom (rx)  : ORIGIN = 0x00000000, LENGTH =  128K
-	ram_local1 (rwx) : ORIGIN = 0x10000000, LENGTH =  96K
-	ram_usb(rw) : ORIGIN = 0x10018000, LENGTH = 32K
-	ram_local2 (rwx) : ORIGIN = 0x10080000, LENGTH =  64K
-	ram_sleep (rwx) : ORIGIN = 0x10090000, LENGTH = 8K
+	rom          (rx)  : ORIGIN = 0x00000000, LENGTH = 128K
+
+	/* - 0x1000 0000 : 96 kB local SRAM ------------------------------------ */
+	ram_local1   (rwx) : ORIGIN = 0x10000000, LENGTH =  96K
+
+	/* - 0x1001 8000 : 32 kB local SRAM (LPC4350/30) ----------------------- */
+	ram_usb      (rw)  : ORIGIN = 0x10018000, LENGTH =  32K
+
+	/* - 0x1002 0000 : reserved -------------------------------------------- */
+
+	/* - 0x1008 0000 : 32kB local SRAM (LPC4350/30/20/10) ------------------ */
+	ram_rtconfig (rx)  : ORIGIN = 0x10080000, LENGTH =  32K
+
+	/* - 0x1008 A000 : 32kB local SRAM (LPC4350/30) ------------------------ */
+	ram_local2   (rwx) : ORIGIN = 0x1008A000, LENGTH =  32K
+
+	/* - 0x1009 0000 : 8kB local SRAM  (LPC4350/30) ------------------------ */
+	ram_sleep    (rwx) : ORIGIN = 0x10090000, LENGTH =   8K
 }
 
 ASSERT(
diff --git a/firmware/common/LPC43xx_M4_memory.ld b/firmware/common/LPC43xx_M4_memory.ld
index fc7dcee7f..0728890c6 100644
--- a/firmware/common/LPC43xx_M4_memory.ld
+++ b/firmware/common/LPC43xx_M4_memory.ld
@@ -22,20 +22,33 @@
 
 MEMORY
 {
-	/* Physical address in Flash used to copy Code from Flash to RAM */
-	rom_flash (rx)    : ORIGIN = 0x80000000, LENGTH = 1M
+	/* UM10503 Rev. 2.5, 10 September 2019
+	 *   - Section 3.3.1  Table 10, LPC43xx/LPC43Sxx SRAM configuration
+	 *   - Section 3.4    Figure 8, Flashless parts: Memory map with peripherals
+	 * LPC4350/30/20/10 Product data sheet Rev. 4.6, 14 March 2016
+	 *   - Section 7.17   Figure 7, LPC4350/30/20/10 Memory mapping (overview)
+	 */
+
+	/* - 0x2000 0000 : 16 kB AHB SRAM (LPC4350/30/20/10) ------------------- */
+	/* - 0x2000 4000 : 16 kB AHB SRAM (LPC4350/30/20) ---------------------- */
 	/* Buffers for LZ4 decompression */
-	ram_lz4_in (rwx)  : ORIGIN = 0x20000000, LENGTH = 4K
-	ram_lz4_out (rwx) : ORIGIN = 0x20001000, LENGTH = 4K
+	ram_lz4_in  (rwx) : ORIGIN = 0x20000000, LENGTH =  4K
+	ram_lz4_out (rwx) : ORIGIN = 0x20001000, LENGTH =  4K
 	/* RAM for M0 code */
-	ram_m0 (rwx)      : ORIGIN = 0x20002000, LENGTH = 20K
+	ram_m0      (rwx) : ORIGIN = 0x20002000, LENGTH = 20K
 	/* RAM shared between M0 and M4 */
-	ram_shared (rwx)  : ORIGIN = 0x20007000, LENGTH = 4K
-	/* USB buffer. Straddles two blocks of RAM
-	 * to get performance benefit of having two USB buffers addressable
-	 * simultaneously (on two different buses of the AHB multilayer matrix)
-	 */
-	ram_samp (rwx)     : ORIGIN = 0x20008000, LENGTH = 32K
+	ram_shared  (rwx) : ORIGIN = 0x20007000, LENGTH =  4K
+
+	/* - 0x2000 8000 : 16 kB AHB SRAM (LPC4350/30/20) ---------------------- */
+	/* - 0x2000 C000 : 16 kB AHB SRAM (LPC4350/30/20/10) ------------------- */
+	/* USB buffer. Straddles two blocks of RAM to get the performance benefit
+	 * of having two USB buffers addressable simultaneously (on two different
+	 * buses of the AHB multilayer matrix) */
+	ram_samp    (rwx) : ORIGIN = 0x20008000, LENGTH = 32K
+
+	/* - 0x8000 0000 : SPIFI data ------------------------------------------ */
+	/* Physical address in Flash used to copy Code from Flash to RAM */
+	rom_flash   (rx)  : ORIGIN = 0x80000000, LENGTH =  1M
 }
 
 lz4_in_buf = ORIGIN(ram_lz4_in);
@@ -43,4 +56,6 @@ lz4_out_buf = ORIGIN(ram_lz4_out);
 usb_samp_buffer = ORIGIN(ram_samp);
 usb_bulk_buffer = ORIGIN(ram_usb);
 m0_state = ORIGIN(ram_shared);
+
+PROVIDE(__ram_rtconfig_start__ = ORIGIN(ram_rtconfig));
 PROVIDE(__ram_m0_start__ = ORIGIN(ram_m0));
diff --git a/firmware/common/LPC43xx_M4_rtconfig.ld b/firmware/common/LPC43xx_M4_rtconfig.ld
new file mode 100644
index 000000000..255fb84d4
--- /dev/null
+++ b/firmware/common/LPC43xx_M4_rtconfig.ld
@@ -0,0 +1,32 @@
+/*
+ * Copyright 2012-2025 Great Scott Gadgets <info@greatscottgadgets.com>
+ * Copyright 2012 Jared Boone <jared@sharebrained.com>
+ *
+ * This file is part of HackRF
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; see the file COPYING.  If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street,
+ * Boston, MA 02110-1301, USA.
+ */
+
+SECTIONS
+{
+    .rtconfig_text : {
+        KEEP(*(.rtconfig));
+        . = ALIGN(4);
+    } >ram_rtconfig AT >rom
+
+    PROVIDE(__rtconfig_start__ = LOADADDR(.rtconfig_text));
+    PROVIDE(__rtconfig_end__ = LOADADDR(.rtconfig_text) + SIZEOF(.rtconfig_text));
+}
diff --git a/firmware/hackrf-common.cmake b/firmware/hackrf-common.cmake
index 8f6698da8..eab114566 100644
--- a/firmware/hackrf-common.cmake
+++ b/firmware/hackrf-common.cmake
@@ -88,9 +88,9 @@ endif()
 
 SET(HACKRF_OPTS "-D${BOARD} -DLPC43XX -D${MCU_PARTNO} -DTX_ENABLE -D'VERSION_STRING=\"${VERSION}\"'")
 
-SET(LDSCRIPT_M4 "-T${PATH_HACKRF_FIRMWARE_COMMON}/${MCU_PARTNO}_M4_memory.ld -Tlibopencm3_lpc43xx_rom_to_ram.ld -T${PATH_HACKRF_FIRMWARE_COMMON}/LPC43xx_M4_M0_image_from_text.ld -T${PATH_HACKRF_FIRMWARE_COMMON}/LPC43xx_M4_memory_rom_only.ld")
+SET(LDSCRIPT_M4 "-T${PATH_HACKRF_FIRMWARE_COMMON}/${MCU_PARTNO}_M4_memory.ld -Tlibopencm3_lpc43xx_rom_to_ram.ld -T${PATH_HACKRF_FIRMWARE_COMMON}/LPC43xx_M4_M0_image_from_text.ld -T${PATH_HACKRF_FIRMWARE_COMMON}/LPC43xx_M4_memory_rom_only.ld -T${PATH_HACKRF_FIRMWARE_COMMON}/LPC43xx_M4_rtconfig.ld")
 
-SET(LDSCRIPT_M4_RAM "-T${PATH_HACKRF_FIRMWARE_COMMON}/${MCU_PARTNO}_M4_memory.ld -Tlibopencm3_lpc43xx.ld -T${PATH_HACKRF_FIRMWARE_COMMON}/LPC43xx_M4_M0_image_from_text.ld")
+SET(LDSCRIPT_M4_RAM "-T${PATH_HACKRF_FIRMWARE_COMMON}/${MCU_PARTNO}_M4_memory.ld -Tlibopencm3_lpc43xx.ld -T${PATH_HACKRF_FIRMWARE_COMMON}/LPC43xx_M4_M0_image_from_text.ld -T${PATH_HACKRF_FIRMWARE_COMMON}/LPC43xx_M4_rtconfig.ld")
 
 SET(LDSCRIPT_M0 "-T${PATH_HACKRF_FIRMWARE_COMMON}/LPC43xx_M0_memory.ld -Tlibopencm3_lpc43xx_m0.ld")
 
diff --git a/firmware/hackrf_usb/hackrf_usb.c b/firmware/hackrf_usb/hackrf_usb.c
index d0c09c612..436385aa8 100644
--- a/firmware/hackrf_usb/hackrf_usb.c
+++ b/firmware/hackrf_usb/hackrf_usb.c
@@ -94,6 +94,9 @@
 extern uint32_t __m0_start__;
 extern uint32_t __m0_end__;
 extern uint32_t __ram_m0_start__;
+extern uint32_t __rtconfig_start__;
+extern uint32_t __rtconfig_end__;
+extern uint32_t __ram_rtconfig_start__;
 extern uint32_t _etext_ram, _text_ram, _etext_rom;
 
 static usb_request_handler_fn vendor_request_handler[] = {
@@ -271,6 +274,20 @@ static void m0_rom_to_ram(void)
 	memcpy(dest, (uint32_t*) (base + src), len);
 }
 
+static void rtconfig_rom_to_ram(void)
+{
+	uint32_t* dest = &__ram_rtconfig_start__;
+
+	// Calculate the base address of ROM
+	uint32_t base = (uint32_t) (&_etext_rom - (&_etext_ram - &_text_ram));
+
+	// rtconfig image location, relative to the start of ROM
+	uint32_t src = (uint32_t) &__rtconfig_start__;
+
+	uint32_t len = (uint32_t) &__rtconfig_end__ - (uint32_t) src;
+	memcpy(dest, (uint32_t*) (base + src), len);
+}
+
 #if defined(IS_PRALINE) && !(defined(DFU_MODE) || defined(RAM_MODE))
 extern uint32_t _binary_fpga_bin_start;
 
@@ -422,6 +439,9 @@ int main(void)
 	// Copy M0 image from ROM before SPIFI is disabled
 	m0_rom_to_ram();
 
+	// Copy rtconfig image from ROM before SPIFI is disabled
+	rtconfig_rom_to_ram();
+
 	// This will be cleared if any self-test check fails.
 	selftest.report.pass = true;
 

From 8bab799d7d8cd6a2b72d7a8b87b44da16a240da3 Mon Sep 17 00:00:00 2001
From: Antoine van Gelder <antoine@greatscottgadgets.com>
Date: Fri, 14 Aug 2026 10:50:32 +0200
Subject: [PATCH 04/11] firmware: add some documentation to top-level linker
 script

---
 firmware/common/LPC4320_M4_memory.ld | 36 ++++++++++++++++++++++++++--
 firmware/common/LPC4330_M4_memory.ld | 15 +++---------
 2 files changed, 37 insertions(+), 14 deletions(-)

diff --git a/firmware/common/LPC4320_M4_memory.ld b/firmware/common/LPC4320_M4_memory.ld
index 984a4e637..182c5b807 100644
--- a/firmware/common/LPC4320_M4_memory.ld
+++ b/firmware/common/LPC4320_M4_memory.ld
@@ -20,7 +20,28 @@
  * Boston, MA 02110-1301, USA.
  */
 
-/* Linker script for HackRF One (LPC4320, 1M SPI flash, 200K SRAM). */
+/* Top-level linker script for HackRF One (LPC4320, 1M SPI flash, 200K SRAM). */
+
+/* Depending on the target, the following additional linker scripts are called:
+ *
+ * `hackrf_usb.bin`:
+ *   - ${MCU_PARTNO}_M4_memory.ld       -> This script
+ *   - LPC43xx_M4_memory.ld             -> Defines additional memory regions
+ *   - LPC43xx_M4_M0_image_from_text.ld -> Adds the M0 core's firmware
+ *   - LPC43xx_M4_memory_rom_only.ld    -> Adds the fpga bitstreams
+ *   - LPC43xx_M4_rtconfig.ld           -> Adds code stored in ram_rtconfig
+ *   - libopencm3_lpc43xx_m0.ld         -> Controls linking for M0 code
+ *   - libopencm3_lpc43xx_rom_to_ram.ld -> Controls linking for M4 and shadow region
+ *
+ * `hackrf_usb.dfu`:
+ *   - ${MCU_PARTNO}_M4_memory.ld       -> This script
+ *   - LPC43xx_M4_memory.ld             -> as above
+ *   - LPC43xx_M0_memory.ld             -> as above
+ *   - LPC43xx_M4_M0_image_from_text.ld -> as above
+ *   - LPC43xx_M4_rtconfig.ld           -> as above
+ *   - libopencm3_lpc43xx.ld            -> Controls linking for M4
+ *   - libopencm3_lpc43xx_m0.ld         -> as above
+ */
 
 MEMORY
 {
@@ -29,12 +50,23 @@ MEMORY
 	 *   - Section 3.3.3  On-chip flash
 	 *   - Section 3.3.5  Memory retention in the Power-down modes
 	 *   - Section 3.4    Figure 8, Flashless parts: Memory map with peripherals
+	 *   - Section 5      LPC43xx Boot ROM
 	 * LPC4350/30/20/10 Product data sheet Rev. 4.6, 14 March 2016
 	 *   - Section 7.17   Figure 7, LPC4350/30/20/10 Memory mapping (overview)
 	 */
 
 	/* - 0x0000 0000 : 256 MB shadow area ---------------------------------- */
-	/* rom is really the shadow region that points to SPI flash or elsewhere */
+	/* The shadow area allows some LPC43xx memory regions to be remapped to
+	 * address 0x0000 0000.
+	 *
+	 * - The default value at RESET is:
+	 *   -> Factory boot ROM @ 0x1040 0000
+	 * - Once the boot ROM has initialized SPIFI and established the boot map
+	 *   it is re-mapped to our 1M SPI Flash:
+	 *   -> SPIFI data       @ 0x1400 0000
+	 * - Next, the `.text_ram` region is copied from SPIFI data to `ram_local1`.
+	 * - Finally, execution jumps to `ram_local1` and the firmware begins.
+	 */
 	rom          (rx)  : ORIGIN = 0x00000000, LENGTH =  1M
 
 	/* - 0x1000 0000 : 96 kB local SRAM ------------------------------------ */
diff --git a/firmware/common/LPC4330_M4_memory.ld b/firmware/common/LPC4330_M4_memory.ld
index 60df2dbea..be4fc6ef5 100644
--- a/firmware/common/LPC4330_M4_memory.ld
+++ b/firmware/common/LPC4330_M4_memory.ld
@@ -20,22 +20,13 @@
  * Boston, MA 02110-1301, USA.
  */
 
-/* Linker script for Rad1o badge - (LPC4330, 1M SPI flash, 264K SRAM). */
+/* Top-level linker script for Rad1o badge (LPC4330, 1M SPI flash, 264K SRAM). */
+
+/* See `LPC4320_M4_memory.ld` for documentation. */
 
 MEMORY
 {
-	/* UM10503 Rev. 2.5, 10 September 2019
-	 *   - Section 3.3.1  Table 10, LPC43xx/LPC43Sxx SRAM configuration
-	 *   - Section 3.3.3  On-chip flash
-	 *   - Section 3.3.5  Memory retention in the Power-down modes
-	 *   - Section 3.4    Figure 8, Flashless parts: Memory map with peripherals
-	 * LPC4350/30/20/10 Product data sheet Rev. 4.6, 14 March 2016
-	 *   - Section 7.17   Figure 7, LPC4350/30/20/10 Memory mapping (overview)
-	 */
-
 	/* - 0x0000 0000 : 256 MB shadow area ---------------------------------- */
-
-	/* rom is really the shadow region that points to SPI flash or elsewhere */
 	rom          (rx)  : ORIGIN = 0x00000000, LENGTH = 128K
 
 	/* - 0x1000 0000 : 96 kB local SRAM ------------------------------------ */

From 66741c6a5f119738bfdcaa3180be44ba7c2a8520 Mon Sep 17 00:00:00 2001
From: Antoine van Gelder <antoine@greatscottgadgets.com>
Date: Fri, 14 Aug 2026 11:12:42 +0200
Subject: [PATCH 05/11] firmware: relocate runtime-configured code to
 ram_rtconfig

---
 firmware/common/platform_gpio.c |  1 +
 firmware/common/platform_scu.c  |  1 +
 firmware/common/portapack.c     |  2 +-
 firmware/common/ui_portapack.c  | 88 ++++++++++++++++++++++-----------
 4 files changed, 61 insertions(+), 31 deletions(-)

diff --git a/firmware/common/platform_gpio.c b/firmware/common/platform_gpio.c
index eeecd90e1..c4a24c730 100644
--- a/firmware/common/platform_gpio.c
+++ b/firmware/common/platform_gpio.c
@@ -27,6 +27,7 @@
 
 // clang-format off
 
+__attribute__((section(".rtconfig")))
 const platform_gpio_t* platform_gpio(void)
 {
 	static const platform_gpio_t* _platform_gpio = NULL;
diff --git a/firmware/common/platform_scu.c b/firmware/common/platform_scu.c
index c9e468e90..e0f5794d4 100644
--- a/firmware/common/platform_scu.c
+++ b/firmware/common/platform_scu.c
@@ -29,6 +29,7 @@
 
 // clang-format off
 
+__attribute__((section(".rtconfig")))
 const platform_scu_t* platform_scu(void)
 {
 	static const platform_scu_t* _platform_scu = NULL;
diff --git a/firmware/common/portapack.c b/firmware/common/portapack.c
index b84bf03c4..ca1923beb 100644
--- a/firmware/common/portapack.c
+++ b/firmware/common/portapack.c
@@ -617,7 +617,7 @@ bool portapack_present(void)
 	return portapack_detected;
 }
 
-bool portapack_init(void)
+__attribute__((section(".rtconfig"))) bool portapack_init(void)
 {
 	if (portapack_detect()) {
 		portapack_if_init();
diff --git a/firmware/common/ui_portapack.c b/firmware/common/ui_portapack.c
index 3387b5ebf..c4326c63a 100644
--- a/firmware/common/ui_portapack.c
+++ b/firmware/common/ui_portapack.c
@@ -33,7 +33,8 @@
 
 /* Pixel data within a font or bitmap byte is "reversed": LSB is left-most pixel. */
 
-static const uint8_t font_fixed_8x16_glyph_data[] = {
+__attribute__((
+	section(".rtconfig"))) static const uint8_t font_fixed_8x16_glyph_data[] = {
 	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08, 0x08,
 	0x00, 0x08, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x24, 0x24, 0x24, 0x24,
@@ -152,10 +153,11 @@ static const uint8_t font_fixed_8x16_glyph_data[] = {
 	0x10, 0x20, 0x10, 0x10, 0x10, 0x10, 0x10, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00,
 	0x00, 0x00, 0x00, 0x00, 0x8e, 0x71, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};
 
-static const ui_font_t font_fixed_8x16 =
+__attribute__((section(".rtconfig"))) static const ui_font_t font_fixed_8x16 =
 	{{8, 16}, font_fixed_8x16_glyph_data, 0x20, 95, (8 * 16 + 7U) >> 3};
 
-static const uint8_t font_fixed_24x19_glyph_data[] = {
+__attribute__((
+	section(".rtconfig"))) static const uint8_t font_fixed_24x19_glyph_data[] = {
 	0xe0, 0xff, 0x07, 0xf8, 0xff, 0x1f, 0xf8, 0xff, 0x1f, 0x3c, 0x00, 0x3c, 0x1c,
 	0x00, 0x38, 0x1c, 0x00, 0x38, 0x1c, 0x00, 0x38, 0x1c, 0x00, 0x38, 0x1c, 0x00,
 	0x38, 0x1c, 0x00, 0x38, 0x1c, 0x00, 0x38, 0x1c, 0x00, 0x38, 0x1c, 0x00, 0x38,
@@ -202,10 +204,11 @@ static const uint8_t font_fixed_24x19_glyph_data[] = {
 	0x00, 0x3c, 0xf8, 0xff, 0x1f, 0xf8, 0xff, 0x1f, 0xe0, 0xff, 0x07,
 };
 
-static const ui_font_t font_fixed_24x19 =
+__attribute__((section(".rtconfig"))) static const ui_font_t font_fixed_24x19 =
 	{{24, 19}, font_fixed_24x19_glyph_data, 0x30, 10, (24 * 19 + 7U) >> 3};
 
-static const uint8_t font_fixed_16x14_glyph_data[] = {
+__attribute__((
+	section(".rtconfig"))) static const uint8_t font_fixed_16x14_glyph_data[] = {
 	0xf8, 0x1f, 0xfc, 0x3f, 0x0e, 0x70, 0x06, 0x60, 0x06, 0x60, 0x06, 0x60, 0x06,
 	0x60, 0x06, 0x60, 0x06, 0x60, 0x06, 0x60, 0x06, 0x60, 0x0e, 0x70, 0xfc, 0x3f,
 	0xf8, 0x1f, 0x00, 0x03, 0x80, 0x03, 0xc0, 0x03, 0xe0, 0x03, 0x70, 0x03, 0x20,
@@ -230,10 +233,10 @@ static const uint8_t font_fixed_16x14_glyph_data[] = {
 	0x60, 0x0e, 0x70, 0xfc, 0x3f, 0xf8, 0x1f,
 };
 
-static const ui_font_t font_fixed_16x14 =
+__attribute__((section(".rtconfig"))) static const ui_font_t font_fixed_16x14 =
 	{{16, 14}, font_fixed_16x14_glyph_data, 0x30, 10, (16 * 14 + 7U) >> 3};
 
-static const uint8_t bitmap_amp_rx_data[] = {
+__attribute__((section(".rtconfig"))) static const uint8_t bitmap_amp_rx_data[] = {
 	0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x06, 0x00, 0x60, 0x06, 0x00, 0x60,
 	0x0c, 0x00, 0x30, 0x0c, 0x00, 0x30, 0x18, 0x00, 0x18, 0x18, 0x00, 0x18,
 	0x30, 0x00, 0x0c, 0x30, 0x00, 0x0c, 0x60, 0x00, 0x06, 0x60, 0x00, 0x06,
@@ -241,9 +244,11 @@ static const uint8_t bitmap_amp_rx_data[] = {
 	0x00, 0xc3, 0x00, 0x00, 0xc3, 0x00, 0x00, 0x66, 0x00, 0x00, 0x66, 0x00,
 	0x00, 0x3c, 0x00, 0x00, 0x3c, 0x00, 0x00, 0x18, 0x00, 0x00, 0x18, 0x00};
 
-static const ui_bitmap_t bitmap_amp_rx = {{24, 24}, bitmap_amp_rx_data};
+__attribute__((section(".rtconfig"))) static const ui_bitmap_t bitmap_amp_rx = {
+	{24, 24},
+	bitmap_amp_rx_data};
 
-static const uint8_t bitmap_amp_tx_data[] = {
+__attribute__((section(".rtconfig"))) static const uint8_t bitmap_amp_tx_data[] = {
 	0x00, 0x18, 0x00, 0x00, 0x18, 0x00, 0x00, 0x3c, 0x00, 0x00, 0x3c, 0x00,
 	0x00, 0x66, 0x00, 0x00, 0x66, 0x00, 0x00, 0xc3, 0x00, 0x00, 0xc3, 0x00,
 	0x80, 0x81, 0x01, 0x80, 0x81, 0x01, 0xc0, 0x00, 0x03, 0xc0, 0x00, 0x03,
@@ -251,9 +256,11 @@ static const uint8_t bitmap_amp_tx_data[] = {
 	0x18, 0x00, 0x18, 0x18, 0x00, 0x18, 0x0c, 0x00, 0x30, 0x0c, 0x00, 0x30,
 	0x06, 0x00, 0x60, 0x06, 0x00, 0x60, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff};
 
-static const ui_bitmap_t bitmap_amp_tx = {{24, 24}, bitmap_amp_tx_data};
+__attribute__((section(".rtconfig"))) static const ui_bitmap_t bitmap_amp_tx = {
+	{24, 24},
+	bitmap_amp_tx_data};
 
-static const uint8_t bitmap_antenna_data[] = {
+__attribute__((section(".rtconfig"))) static const uint8_t bitmap_antenna_data[] = {
 	0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x06, 0x18, 0x60, 0x06, 0x18, 0x60,
 	0x0c, 0x18, 0x30, 0x0c, 0x18, 0x30, 0x18, 0x18, 0x18, 0x18, 0x18, 0x18,
 	0x30, 0x18, 0x0c, 0x30, 0x18, 0x0c, 0x60, 0x18, 0x06, 0x60, 0x18, 0x06,
@@ -261,9 +268,11 @@ static const uint8_t bitmap_antenna_data[] = {
 	0x00, 0xdb, 0x00, 0x00, 0xdb, 0x00, 0x00, 0x7e, 0x00, 0x00, 0x7e, 0x00,
 	0x00, 0x3c, 0x00, 0x00, 0x3c, 0x00, 0x00, 0x18, 0x00, 0x00, 0x18, 0x00};
 
-static const ui_bitmap_t bitmap_antenna = {{24, 24}, bitmap_antenna_data};
+__attribute__((section(".rtconfig"))) static const ui_bitmap_t bitmap_antenna = {
+	{24, 24},
+	bitmap_antenna_data};
 
-static const uint8_t bitmap_filter_hp_data[] = {
+__attribute__((section(".rtconfig"))) static const uint8_t bitmap_filter_hp_data[] = {
 	0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x03, 0x00, 0xc0, 0x03, 0x00, 0xc0,
 	0x03, 0x00, 0xc0, 0x03, 0x00, 0xc0, 0x03, 0xf8, 0xc7, 0x03, 0xfc, 0xc7,
 	0x03, 0x0e, 0xc0, 0x03, 0x06, 0xc0, 0x03, 0x03, 0xc0, 0x03, 0x03, 0xc0,
@@ -271,9 +280,11 @@ static const uint8_t bitmap_filter_hp_data[] = {
 	0x63, 0x00, 0xc0, 0x63, 0x00, 0xc0, 0x03, 0x00, 0xc0, 0x03, 0x00, 0xc0,
 	0x03, 0x00, 0xc0, 0x03, 0x00, 0xc0, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff};
 
-static const ui_bitmap_t bitmap_filter_hp = {{24, 24}, bitmap_filter_hp_data};
+__attribute__((section(".rtconfig"))) static const ui_bitmap_t bitmap_filter_hp = {
+	{24, 24},
+	bitmap_filter_hp_data};
 
-static const uint8_t bitmap_filter_lp_data[] = {
+__attribute__((section(".rtconfig"))) static const uint8_t bitmap_filter_lp_data[] = {
 	0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x03, 0x00, 0xc0, 0x03, 0x00, 0xc0,
 	0x03, 0x00, 0xc0, 0x03, 0x00, 0xc0, 0xe3, 0x1f, 0xc0, 0xe3, 0x3f, 0xc0,
 	0x03, 0x70, 0xc0, 0x03, 0x60, 0xc0, 0x03, 0xc0, 0xc0, 0x03, 0xc0, 0xc0,
@@ -281,9 +292,11 @@ static const uint8_t bitmap_filter_lp_data[] = {
 	0x03, 0x00, 0xc6, 0x03, 0x00, 0xc6, 0x03, 0x00, 0xc0, 0x03, 0x00, 0xc0,
 	0x03, 0x00, 0xc0, 0x03, 0x00, 0xc0, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff};
 
-static const ui_bitmap_t bitmap_filter_lp = {{24, 24}, bitmap_filter_lp_data};
+__attribute__((section(".rtconfig"))) static const ui_bitmap_t bitmap_filter_lp = {
+	{24, 24},
+	bitmap_filter_lp_data};
 
-static const uint8_t bitmap_mixer_data[] = {
+__attribute__((section(".rtconfig"))) static const uint8_t bitmap_mixer_data[] = {
 	0x00, 0x7e, 0x00, 0xc0, 0xff, 0x03, 0xe0, 0x81, 0x07, 0x70, 0x00, 0x0e,
 	0x38, 0x00, 0x1c, 0x7c, 0x00, 0x3e, 0xee, 0x00, 0x77, 0xc6, 0x81, 0x63,
 	0x86, 0xc3, 0x61, 0x03, 0xe7, 0xc0, 0x03, 0x7e, 0xc0, 0x03, 0x3c, 0xc0,
@@ -291,9 +304,11 @@ static const uint8_t bitmap_mixer_data[] = {
 	0xc6, 0x81, 0x63, 0xee, 0x00, 0x77, 0x7c, 0x00, 0x3e, 0x38, 0x00, 0x1c,
 	0x70, 0x00, 0x0e, 0xe0, 0x81, 0x07, 0xc0, 0xff, 0x03, 0x00, 0x7e, 0x00};
 
-static const ui_bitmap_t bitmap_mixer = {{24, 24}, bitmap_mixer_data};
+__attribute__((section(".rtconfig"))) static const ui_bitmap_t bitmap_mixer = {
+	{24, 24},
+	bitmap_mixer_data};
 
-static const uint8_t bitmap_oscillator_data[] = {
+__attribute__((section(".rtconfig"))) static const uint8_t bitmap_oscillator_data[] = {
 	0x00, 0x7e, 0x00, 0xc0, 0xff, 0x03, 0xe0, 0x81, 0x07, 0x70, 0x00, 0x0e,
 	0x38, 0x00, 0x1c, 0x1c, 0x00, 0x38, 0x0e, 0x03, 0x70, 0x86, 0x07, 0x60,
 	0xc6, 0x0f, 0x60, 0xc3, 0x0c, 0xc0, 0xe3, 0x1c, 0xc0, 0x63, 0x18, 0xc6,
@@ -301,13 +316,18 @@ static const uint8_t bitmap_oscillator_data[] = {
 	0x06, 0xe0, 0x61, 0x0e, 0xc0, 0x70, 0x1c, 0x00, 0x38, 0x38, 0x00, 0x1c,
 	0x70, 0x00, 0x0e, 0xe0, 0x81, 0x07, 0xc0, 0xff, 0x03, 0x00, 0x7e, 0x00};
 
-static const ui_bitmap_t bitmap_oscillator = {{24, 24}, bitmap_oscillator_data};
+__attribute__((section(".rtconfig"))) static const ui_bitmap_t bitmap_oscillator = {
+	{24, 24},
+	bitmap_oscillator_data};
 
-static const uint8_t bitmap_wire_8_data[] = {0xff, 0xff};
+__attribute__((
+	section(".rtconfig"))) static const uint8_t bitmap_wire_8_data[] = {0xff, 0xff};
 
-static const ui_bitmap_t bitmap_wire_8 = {{2, 8}, bitmap_wire_8_data};
+__attribute__((section(".rtconfig"))) static const ui_bitmap_t bitmap_wire_8 = {
+	{2, 8},
+	bitmap_wire_8_data};
 
-static const uint8_t bitmap_wire_24_data[] = {
+__attribute__((section(".rtconfig"))) static const uint8_t bitmap_wire_24_data[] = {
 	0x00, 0x18, 0x00, 0x00, 0x18, 0x00, 0x00, 0x18, 0x00, 0x00, 0x18, 0x00,
 	0x00, 0x18, 0x00, 0x00, 0x18, 0x00, 0x00, 0x18, 0x00, 0x00, 0x18, 0x00,
 	0x00, 0x18, 0x00, 0x00, 0x18, 0x00, 0x00, 0x18, 0x00, 0x00, 0x18, 0x00,
@@ -315,9 +335,11 @@ static const uint8_t bitmap_wire_24_data[] = {
 	0x00, 0x18, 0x00, 0x00, 0x18, 0x00, 0x00, 0x18, 0x00, 0x00, 0x18, 0x00,
 	0x00, 0x18, 0x00, 0x00, 0x18, 0x00, 0x00, 0x18, 0x00, 0x00, 0x18, 0x00};
 
-static const ui_bitmap_t bitmap_wire_24 = {{24, 24}, bitmap_wire_24_data};
+__attribute__((section(".rtconfig"))) static const ui_bitmap_t bitmap_wire_24 = {
+	{24, 24},
+	bitmap_wire_24_data};
 
-static const uint8_t bitmap_blank_24_data[] = {
+__attribute__((section(".rtconfig"))) static const uint8_t bitmap_blank_24_data[] = {
 	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
@@ -325,23 +347,29 @@ static const uint8_t bitmap_blank_24_data[] = {
 	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};
 
-static const ui_bitmap_t bitmap_blank_24 = {{24, 24}, bitmap_blank_24_data};
+__attribute__((section(".rtconfig"))) static const ui_bitmap_t bitmap_blank_24 = {
+	{24, 24},
+	bitmap_blank_24_data};
 
-static const uint8_t bitmap_waves_rx_data[] = {
+__attribute__((section(".rtconfig"))) static const uint8_t bitmap_waves_rx_data[] = {
 	0xc0, 0x00, 0x60, 0x00, 0x70, 0x06, 0x30, 0x07, 0x38, 0x03, 0x98, 0x33,
 	0x98, 0x39, 0x98, 0x19, 0xcc, 0x18, 0xcc, 0x0c, 0xcc, 0x0c, 0xcc, 0x0c,
 	0xcc, 0x0c, 0xcc, 0x0c, 0xcc, 0x0c, 0xcc, 0x18, 0x98, 0x19, 0x98, 0x39,
 	0x98, 0x33, 0x38, 0x03, 0x30, 0x07, 0x70, 0x06, 0x60, 0x00, 0xc0, 0x00};
 
-static const ui_bitmap_t bitmap_waves_rx = {{16, 24}, bitmap_waves_rx_data};
+__attribute__((section(".rtconfig"))) static const ui_bitmap_t bitmap_waves_rx = {
+	{16, 24},
+	bitmap_waves_rx_data};
 
-static const uint8_t bitmap_waves_tx_data[] = {
+__attribute__((section(".rtconfig"))) static const uint8_t bitmap_waves_tx_data[] = {
 	0x00, 0x03, 0x00, 0x06, 0x60, 0x0e, 0xe0, 0x0c, 0xc0, 0x1c, 0xcc, 0x19,
 	0x9c, 0x19, 0x98, 0x19, 0x18, 0x33, 0x30, 0x33, 0x30, 0x33, 0x30, 0x33,
 	0x30, 0x33, 0x30, 0x33, 0x30, 0x33, 0x18, 0x33, 0x98, 0x19, 0x9c, 0x19,
 	0xcc, 0x19, 0xc0, 0x1c, 0xe0, 0x0c, 0x60, 0x0e, 0x00, 0x06, 0x00, 0x03};
 
-static const ui_bitmap_t bitmap_waves_tx = {{16, 24}, bitmap_waves_tx_data};
+__attribute__((section(".rtconfig"))) static const ui_bitmap_t bitmap_waves_tx = {
+	{16, 24},
+	bitmap_waves_tx_data};
 
 __attribute__((unused)) static ui_color_t portapack_color_rgb(
 	const uint_fast8_t r,

From a3ab28c36b46e437cb742b6d8e9239549e6ac990 Mon Sep 17 00:00:00 2001
From: Antoine van Gelder <antoine@greatscottgadgets.com>
Date: Fri, 14 Aug 2026 11:13:01 +0200
Subject: [PATCH 06/11] firmware: add -Wl,--print-memory-usage to LDFLAGS

---
 firmware/hackrf-common.cmake | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/firmware/hackrf-common.cmake b/firmware/hackrf-common.cmake
index eab114566..0bd85f7f8 100644
--- a/firmware/hackrf-common.cmake
+++ b/firmware/hackrf-common.cmake
@@ -95,7 +95,7 @@ SET(LDSCRIPT_M4_RAM "-T${PATH_HACKRF_FIRMWARE_COMMON}/${MCU_PARTNO}_M4_memory.ld
 SET(LDSCRIPT_M0 "-T${PATH_HACKRF_FIRMWARE_COMMON}/LPC43xx_M0_memory.ld -Tlibopencm3_lpc43xx_m0.ld")
 
 SET(CFLAGS_COMMON "-Os -g3 -Wall -Wextra -Wstrict-prototypes -Wold-style-definition ${HACKRF_OPTS} -fno-common -MD")
-SET(LDFLAGS_COMMON "-nostartfiles -Wl,--gc-sections")
+SET(LDFLAGS_COMMON "-nostartfiles -Wl,--gc-sections -Wl,--print-memory-usage")
 
 if(V STREQUAL "1")
 	SET(LDFLAGS_COMMON "${LDFLAGS_COMMON} -Wl,--print-gc-sections")

From f657bedc776a6730e979421d7f95db047d299122 Mon Sep 17 00:00:00 2001
From: Antoine van Gelder <antoine@greatscottgadgets.com>
Date: Mon, 1 Jun 2026 14:39:45 +0200
Subject: [PATCH 07/11] radio: Add support for locking radio registers

---
 firmware/common/radio.c                | 24 ++++++++++
 firmware/common/radio.h                | 11 +++++
 firmware/hackrf_usb/hackrf_usb.c       |  1 +
 firmware/hackrf_usb/usb_api_register.c | 17 +++++++
 firmware/hackrf_usb/usb_api_register.h |  3 ++
 firmware/hackrf_usb/usb_descriptor.c   |  2 +-
 host/hackrf-tools/src/hackrf_debug.c   | 65 ++++++++++++++++++++++++--
 host/libhackrf/src/hackrf.c            | 28 +++++++++++
 host/libhackrf/src/hackrf.h            | 14 ++++++
 9 files changed, 159 insertions(+), 6 deletions(-)

diff --git a/firmware/common/radio.c b/firmware/common/radio.c
index 36f65cad7..b947cd624 100644
--- a/firmware/common/radio.c
+++ b/firmware/common/radio.c
@@ -60,6 +60,7 @@ void radio_init(radio_t* const radio)
 	radio->config[RADIO_BANK_TX][RADIO_OPMODE] = TRANSCEIVER_MODE_TX;
 	radio->config[RADIO_BANK_IDLE][RADIO_BIAS_TEE] = false;
 	radio->regs_dirty = 0;
+	radio->regs_locked = 0;
 }
 
 static inline void mark_dirty(radio_t* const radio, radio_register_t reg)
@@ -67,6 +68,11 @@ static inline void mark_dirty(radio_t* const radio, radio_register_t reg)
 	radio->regs_dirty |= (1 << reg);
 }
 
+static inline bool check_locked(radio_t* const radio, radio_register_t reg)
+{
+	return radio->regs_locked & (1 << reg);
+}
+
 radio_error_t radio_reg_write(
 	radio_t* const radio,
 	const radio_register_bank_t bank,
@@ -77,6 +83,10 @@ radio_error_t radio_reg_write(
 		return RADIO_ERR_INVALID_REGISTER;
 	}
 
+	if (check_locked(radio, reg)) {
+		return RADIO_ERR_LOCKED_REGISTER;
+	}
+
 	switch (bank) {
 	case RADIO_BANK_REQUESTED:
 		mark_dirty(radio, reg);
@@ -107,6 +117,20 @@ uint64_t radio_reg_read(
 	return radio->config[bank][reg];
 }
 
+radio_error_t radio_reg_lock(
+	radio_t* const radio,
+	const radio_register_t reg,
+	const bool locked)
+{
+	if (reg > RADIO_NUM_REGS) {
+		return RADIO_ERR_INVALID_REGISTER;
+	}
+
+	radio->regs_locked = (radio->regs_locked & ~(1 << reg)) | (locked << reg);
+
+	return RADIO_OK;
+}
+
 static uint32_t radio_update_direction(radio_t* const radio, uint64_t* bank)
 {
 	const uint64_t requested = bank[RADIO_OPMODE];
diff --git a/firmware/common/radio.h b/firmware/common/radio.h
index 8e12471a4..caaa222d3 100644
--- a/firmware/common/radio.h
+++ b/firmware/common/radio.h
@@ -34,6 +34,7 @@ typedef enum {
 	RADIO_ERR_INVALID_PARAM = -2,
 	RADIO_ERR_INVALID_BANK = -3,
 	RADIO_ERR_INVALID_REGISTER = -4,
+	RADIO_ERR_LOCKED_REGISTER = -5,
 	RADIO_ERR_UNSUPPORTED_OPERATION = -10,
 	RADIO_ERR_UNIMPLEMENTED = -19,
 	RADIO_ERR_OTHER = -9999,
@@ -231,6 +232,7 @@ typedef struct {
 	radio_config_mode_t config_mode;
 	uint64_t config[RADIO_NUM_BANKS][RADIO_NUM_REGS];
 	volatile uint32_t regs_dirty;
+	uint32_t regs_locked;
 	update_fn update_cb;
 } radio_t;
 
@@ -254,6 +256,15 @@ uint64_t radio_reg_read(
 	const radio_register_bank_t bank,
 	const radio_register_t reg);
 
+/**
+ * Lock a register. Prevents any future calls to `radio_reg_write`
+ * from overwriting the current stored value of the register.
+ */
+radio_error_t radio_reg_lock(
+	radio_t* const radio,
+	const radio_register_t reg,
+	const bool locked);
+
 /**
  * Apply changes requested in RADIO_BANK_REQUESTED.
  * Return true if any changes were applied.
diff --git a/firmware/hackrf_usb/hackrf_usb.c b/firmware/hackrf_usb/hackrf_usb.c
index 436385aa8..43b636d9e 100644
--- a/firmware/hackrf_usb/hackrf_usb.c
+++ b/firmware/hackrf_usb/hackrf_usb.c
@@ -186,6 +186,7 @@ static usb_request_handler_fn vendor_request_handler[] = {
 	usb_vendor_request_read_radio_reg,
 	usb_vendor_request_get_buffer_size,
 	usb_vendor_request_read_temperature,
+	usb_vendor_request_lock_radio_reg,
 };
 
 static const uint32_t vendor_request_handler_count =
diff --git a/firmware/hackrf_usb/usb_api_register.c b/firmware/hackrf_usb/usb_api_register.c
index 626c75089..a46a22404 100644
--- a/firmware/hackrf_usb/usb_api_register.c
+++ b/firmware/hackrf_usb/usb_api_register.c
@@ -416,3 +416,20 @@ usb_request_status_t usb_vendor_request_read_radio_reg(
 	}
 	return USB_REQUEST_STATUS_OK;
 }
+
+usb_request_status_t usb_vendor_request_lock_radio_reg(
+	usb_endpoint_t* const endpoint,
+	const usb_transfer_stage_t stage)
+{
+	if (stage == USB_TRANSFER_STAGE_SETUP) {
+		uint8_t reg = endpoint->setup.index;
+		bool locked = endpoint->setup.value != 0 ? true : false;
+		if (reg >= RADIO_NUM_REGS) {
+			return USB_REQUEST_STATUS_STALL;
+		}
+		radio_reg_lock(&radio, reg, locked);
+		usb_transfer_schedule_ack(endpoint->in);
+	}
+
+	return USB_REQUEST_STATUS_OK;
+}
diff --git a/firmware/hackrf_usb/usb_api_register.h b/firmware/hackrf_usb/usb_api_register.h
index a5a36550d..7e434c1a7 100644
--- a/firmware/hackrf_usb/usb_api_register.h
+++ b/firmware/hackrf_usb/usb_api_register.h
@@ -70,3 +70,6 @@ usb_request_status_t usb_vendor_request_write_radio_reg(
 usb_request_status_t usb_vendor_request_read_radio_reg(
 	usb_endpoint_t* const endpoint,
 	const usb_transfer_stage_t stage);
+usb_request_status_t usb_vendor_request_lock_radio_reg(
+	usb_endpoint_t* const endpoint,
+	const usb_transfer_stage_t stage);
diff --git a/firmware/hackrf_usb/usb_descriptor.c b/firmware/hackrf_usb/usb_descriptor.c
index dde22e6e3..726e126a0 100644
--- a/firmware/hackrf_usb/usb_descriptor.c
+++ b/firmware/hackrf_usb/usb_descriptor.c
@@ -28,7 +28,7 @@
 
 #define USB_VENDOR_ID (0x1D50)
 
-#define USB_API_VERSION (0x0113)
+#define USB_API_VERSION (0x0114)
 
 #define USB_WORD(x) (x & 0xFF), ((x >> 8) & 0xFF)
 
diff --git a/host/hackrf-tools/src/hackrf_debug.c b/host/hackrf-tools/src/hackrf_debug.c
index c009e84cf..f179090f7 100644
--- a/host/hackrf-tools/src/hackrf_debug.c
+++ b/host/hackrf-tools/src/hackrf_debug.c
@@ -545,6 +545,30 @@ int radio_write_register(
 	return result;
 }
 
+int radio_lock_register(
+	hackrf_device* device,
+	const uint16_t register_number,
+	const bool register_locked)
+{
+	int result = HACKRF_SUCCESS;
+	result = hackrf_radio_lock_register(
+		device,
+		(uint8_t) register_number,
+		register_locked);
+
+	if (result == HACKRF_SUCCESS) {
+		printf("register [%2d] -> %s\n",
+		       register_number,
+		       register_locked ? "locked" : "unlocked");
+	} else {
+		printf("hackrf_radio_lock_register() failed: %s (%d)\n",
+		       hackrf_error_name(result),
+		       result);
+	}
+
+	return result;
+}
+
 int read_register(
 	hackrf_device* device,
 	uint8_t part,
@@ -621,6 +645,20 @@ int write_register(
 	return HACKRF_ERROR_INVALID_PARAM;
 }
 
+int lock_register(
+	hackrf_device* device,
+	uint8_t part,
+	const uint16_t register_number,
+	const bool register_locked)
+{
+	switch (part) {
+	case PART_RADIO:
+		return radio_lock_register(device, register_number, register_locked);
+	default:
+		return HACKRF_ERROR_INVALID_PARAM;
+	}
+}
+
 static const char* mode_name(uint32_t mode)
 {
 	const char* mode_names[] = {"IDLE", "WAIT", "RX", "TX_START", "TX_RUN"};
@@ -675,6 +713,7 @@ static void usage()
 	printf("\t-n, --register <n>: set register number for read/write operations\n");
 	printf("\t-r, --read: read register specified by last -n argument, or all registers\n");
 	printf("\t-w, --write <v>: write register specified by last -n argument with value <v>\n");
+	printf("\t-L, --lock <state>: lock register specified by last -n argument (0 for unlocked, 1 for locked)\n");
 	printf("\t-c, --config: print SI5351C multisynth configuration information\n");
 	printf("\t-d, --device <s>: specify a particular device by serial number\n");
 	printf("\t-m, --max283x: target MAX283x\n");
@@ -710,6 +749,7 @@ static struct option long_options[] = {
 	{"register", required_argument, 0, 'n'},
 	{"write", required_argument, 0, 'w'},
 	{"read", no_argument, 0, 'r'},
+	{"lock", required_argument, 0, 'L'},
 	{"device", required_argument, 0, 'd'},
 	{"help", no_argument, 0, 'h'},
 	{"max2837", no_argument, 0, 'm'},
@@ -742,10 +782,12 @@ int main(int argc, char** argv)
 	int bank = -1;
 	uint64_t register_number = REGISTER_INVALID;
 	uint64_t register_value;
+	uint64_t register_locked;
 	hackrf_device* device = NULL;
 	int option_index = 0;
 	bool read = false;
 	bool write = false;
+	bool lock = false;
 	bool dump_config = false;
 	bool dump_state = false;
 	uint8_t part = PART_NONE;
@@ -785,7 +827,7 @@ int main(int argc, char** argv)
 	while ((opt = getopt_long(
 			argc,
 			argv,
-			"b:n:rw:d:cmsfgi1:2:C:N:P:ST:R:h?u:l:ta:op",
+			"b:n:rw:L:d:cmsfgi1:2:C:N:P:ST:R:h?u:l:ta:op",
 			long_options,
 			&option_index)) != EOF) {
 		switch (opt) {
@@ -808,6 +850,11 @@ int main(int argc, char** argv)
 			read = true;
 			break;
 
+		case 'L':
+			lock = true;
+			result = parse_int(optarg, &register_locked);
+			break;
+
 		case 'c':
 			dump_config = true;
 			break;
@@ -938,8 +985,8 @@ int main(int argc, char** argv)
 		}
 	}
 
-	if (write && read) {
-		fprintf(stderr, "Read and write options are mutually exclusive.\n");
+	if ((write && read) || (lock && write) || (lock && read)) {
+		fprintf(stderr, "Read, write and lock options are mutually exclusive.\n");
 		usage();
 		return EXIT_FAILURE;
 	}
@@ -956,6 +1003,10 @@ int main(int argc, char** argv)
 		return EXIT_FAILURE;
 	}
 
+	if (lock && part != PART_RADIO) {
+		fprintf(stderr, "Lock option is only valid for radio.\n");
+	}
+
 	if ((bank > -1) && (part != PART_RADIO)) {
 		fprintf(stderr, "Bank valid only for radio.\n");
 		usage();
@@ -966,11 +1017,11 @@ int main(int argc, char** argv)
 		bank = 0;
 	}
 
-	if (!(write || read || dump_config || dump_state || set_tx_limit ||
+	if (!(write || read || lock || dump_config || dump_state || set_tx_limit ||
 	      set_rx_limit || set_ui || set_leds || set_p1 || set_p2 || set_clkin ||
 	      set_narrowband || set_fpga_bitstream || read_selftest || test_rtc_osc ||
 	      read_adc || read_temp)) {
-		fprintf(stderr, "Specify read, write, or config option.\n");
+		fprintf(stderr, "Specify read, write, lock, or config option.\n");
 		usage();
 		return EXIT_FAILURE;
 	}
@@ -1023,6 +1074,10 @@ int main(int argc, char** argv)
 		}
 	}
 
+	if (lock) {
+		result = lock_register(device, part, register_number, register_locked);
+	}
+
 	if (dump_config) {
 		si5351c_read_configuration(device);
 	}
diff --git a/host/libhackrf/src/hackrf.c b/host/libhackrf/src/hackrf.c
index 2efbfea42..80e8d3196 100644
--- a/host/libhackrf/src/hackrf.c
+++ b/host/libhackrf/src/hackrf.c
@@ -122,6 +122,7 @@ typedef enum {
 	HACKRF_VENDOR_REQUEST_RADIO_READ_REG = 60,
 	HACKRF_VENDOR_REQUEST_GET_BUFFER_SIZE = 61,
 	HACKRF_VENDOR_REQUEST_READ_TEMPERATURE = 62,
+	HACKRF_VENDOR_REQUEST_RADIO_LOCK_REG = 63,
 } hackrf_vendor_request;
 
 #define USB_CONFIG_STANDARD 0x1
@@ -3598,6 +3599,33 @@ int ADDCALL hackrf_radio_write_register(
 	}
 }
 
+int ADDCALL hackrf_radio_lock_register(
+	hackrf_device* device,
+	const uint8_t register_number,
+	const bool register_locked)
+{
+	USB_API_REQUIRED(device, 0x0114);
+	int result;
+
+	result = libusb_control_transfer(
+		device->usb_device,
+		LIBUSB_ENDPOINT_OUT | LIBUSB_REQUEST_TYPE_VENDOR |
+			LIBUSB_RECIPIENT_DEVICE,
+		HACKRF_VENDOR_REQUEST_RADIO_LOCK_REG,
+		register_locked,
+		register_number,
+		NULL,
+		0,
+		DEFAULT_REQUEST_TIMEOUT);
+
+	if (result != 0) {
+		last_libusb_error = result;
+		return HACKRF_ERROR_LIBUSB;
+	}
+
+	return HACKRF_SUCCESS;
+}
+
 #ifdef __cplusplus
 } // __cplusplus defined.
 #endif
diff --git a/host/libhackrf/src/hackrf.h b/host/libhackrf/src/hackrf.h
index d9322d3c2..e0c09cda4 100644
--- a/host/libhackrf/src/hackrf.h
+++ b/host/libhackrf/src/hackrf.h
@@ -2395,6 +2395,20 @@ extern ADDAPI int ADDCALL hackrf_radio_write_register(
 	const uint8_t register_number,
 	const uint64_t value);
 
+/**
+ * Lock or unlock a radio configuration register.
+ *
+ * @param[in] device device to write
+ * @param[in] register_number register number to mask
+ * @param[out] locked locked state for the register
+ * @return @ref HACKRF_SUCCESS on success or @ref hackrf_error variant
+ * @ingroup debug
+ */
+extern ADDAPI int ADDCALL hackrf_radio_lock_register(
+	hackrf_device* device,
+	const uint8_t register_number,
+	const bool register_locked);
+
 #ifdef __cplusplus
 } // __cplusplus defined.
 #endif

From 45bc687d5a35d4c04a335bc834487029666736ce Mon Sep 17 00:00:00 2001
From: Antoine van Gelder <antoine@greatscottgadgets.com>
Date: Wed, 24 Jun 2026 11:01:46 +0200
Subject: [PATCH 08/11] radio: add radio_set_config_mode()

---
 firmware/common/fpga.h  |  8 +++++
 firmware/common/radio.c | 68 +++++++++++++++++++++++++++++++++++++++++
 firmware/common/radio.h |  9 ++++++
 3 files changed, 85 insertions(+)

diff --git a/firmware/common/fpga.h b/firmware/common/fpga.h
index 1765fcdd1..58152e687 100644
--- a/firmware/common/fpga.h
+++ b/firmware/common/fpga.h
@@ -26,6 +26,14 @@
 
 #include "ice40_spi.h"
 
+/* Supported Bitstreams. */
+typedef enum {
+	FPGA_BITSTREAM_STANDARD = 0,
+	FPGA_BITSTREAM_HALFPREC = 1,
+	FPGA_BITSTREAM_EXTPREC_RX = 2,
+	FPGA_BITSTREAM_EXTPREC_TX = 3,
+} fpga_bitstream_index_t;
+
 /* Up to 7 registers, each containing up to 8 bits of data */
 #define FPGA_NUM_REGS            7
 #define FPGA_DATA_REGS_MAX_VALUE 255
diff --git a/firmware/common/radio.c b/firmware/common/radio.c
index b947cd624..6cd46b82f 100644
--- a/firmware/common/radio.c
+++ b/firmware/common/radio.c
@@ -1034,3 +1034,71 @@ void radio_switch_opmode(radio_t* const radio, const transceiver_mode_t mode)
 	nvic_enable_irq(NVIC_USB0_IRQ);
 	radio_update(radio);
 }
+
+bool radio_set_config_mode(radio_t* const radio, const radio_config_mode_t mode)
+{
+	// Check if the requested mode is supported.
+	switch (mode) {
+	case RADIO_CONFIG_LEGACY:
+	case RADIO_CONFIG_STANDARD:
+		// supported on all boards
+		break;
+#ifdef IS_PRALINE
+	case RADIO_CONFIG_HALF_PRECISION:
+	case RADIO_CONFIG_EXT_PRECISION_RX:
+	case RADIO_CONFIG_EXT_PRECISION_TX:
+		// only supported on praline
+		if (!IS_PRALINE) {
+			return false;
+		}
+		break;
+#endif
+	default:
+		return false;
+	}
+
+	// Don't do anything if we're already in the requested mode.
+	if (mode == radio->config_mode) {
+		return true;
+	}
+
+#if defined(IS_PRALINE) && !(defined(DFU_MODE) || defined(RAM_MODE))
+	if (IS_PRALINE) {
+		fpga_bitstream_index_t bitstream_index;
+		switch (mode) {
+		case RADIO_CONFIG_LEGACY:
+		case RADIO_CONFIG_STANDARD:
+			bitstream_index = FPGA_BITSTREAM_STANDARD;
+			break;
+		case RADIO_CONFIG_HALF_PRECISION:
+			bitstream_index = FPGA_BITSTREAM_HALFPREC;
+			break;
+		case RADIO_CONFIG_EXT_PRECISION_RX:
+			bitstream_index = FPGA_BITSTREAM_EXTPREC_RX;
+			break;
+		case RADIO_CONFIG_EXT_PRECISION_TX:
+			bitstream_index = FPGA_BITSTREAM_EXTPREC_TX;
+			break;
+		default:
+			return false;
+		}
+
+		// Reset radio state.
+		for (uint8_t reg = 0; reg < RADIO_NUM_REGS; reg++) {
+			radio_reg_write(radio, RADIO_BANK_APPLIED, reg, RADIO_UNSET);
+			radio_reg_write(radio, RADIO_BANK_REQUESTED, reg, RADIO_UNSET);
+		}
+
+		// Load bitstream.
+		extern struct fpga_loader_t fpga_loader;
+		if (!fpga_image_load(&fpga_loader, bitstream_index)) {
+			return false;
+		}
+	}
+#endif
+
+	// Update radio config mode.
+	radio->config_mode = mode;
+
+	return true;
+}
diff --git a/firmware/common/radio.h b/firmware/common/radio.h
index caaa222d3..96ced41b6 100644
--- a/firmware/common/radio.h
+++ b/firmware/common/radio.h
@@ -41,12 +41,15 @@ typedef enum {
 } radio_error_t;
 
 /* radio configuration modes */
+// TODO are we sure we need a legacy mode?
 typedef enum {
 	RADIO_CONFIG_LEGACY = 0,
 	RADIO_CONFIG_STANDARD = 1,
+#ifdef IS_PRALINE
 	RADIO_CONFIG_EXT_PRECISION_RX = 2,
 	RADIO_CONFIG_EXT_PRECISION_TX = 3,
 	RADIO_CONFIG_HALF_PRECISION = 4,
+#endif
 } radio_config_mode_t;
 
 typedef struct {
@@ -277,6 +280,12 @@ bool radio_update(radio_t* const radio);
  */
 void radio_switch_opmode(radio_t* const radio, const transceiver_mode_t mode);
 
+/**
+ * Switch to a new configuration mode.
+ * Return true if the mode was successfully switched.
+ */
+bool radio_set_config_mode(radio_t* const radio, const radio_config_mode_t mode);
+
 /**
  * Driver instance.
  */

From bcd00011d42d5a23e472d52cb20be06223fe7477 Mon Sep 17 00:00:00 2001
From: Antoine van Gelder <antoine@greatscottgadgets.com>
Date: Mon, 22 Jun 2026 16:40:10 +0200
Subject: [PATCH 09/11] Add 'hackrf_open_mode()',
 'hackrf_open_mode_by_serial()' and 'hackrf_device_list_open_mode()'

---
 firmware/common/radio.c                   |  1 +
 firmware/hackrf_usb/hackrf_usb.c          |  2 +
 firmware/hackrf_usb/usb_api_transceiver.c | 36 +++++++++
 firmware/hackrf_usb/usb_api_transceiver.h |  6 ++
 host/libhackrf/src/hackrf.c               | 95 ++++++++++++++++++++---
 host/libhackrf/src/hackrf.h               | 64 +++++++++++++++
 6 files changed, 194 insertions(+), 10 deletions(-)

diff --git a/firmware/common/radio.c b/firmware/common/radio.c
index 6cd46b82f..167d08340 100644
--- a/firmware/common/radio.c
+++ b/firmware/common/radio.c
@@ -53,6 +53,7 @@ void radio_init(radio_t* const radio)
 			radio->config[bank][reg] = RADIO_UNSET;
 		}
 	}
+	radio->config_mode = RADIO_CONFIG_STANDARD;
 	radio->config[RADIO_BANK_APPLIED][RADIO_OPMODE] = TRANSCEIVER_MODE_OFF;
 	radio->config[RADIO_BANK_REQUESTED][RADIO_OPMODE] = TRANSCEIVER_MODE_OFF;
 	radio->config[RADIO_BANK_IDLE][RADIO_OPMODE] = TRANSCEIVER_MODE_OFF;
diff --git a/firmware/hackrf_usb/hackrf_usb.c b/firmware/hackrf_usb/hackrf_usb.c
index 43b636d9e..5862048d0 100644
--- a/firmware/hackrf_usb/hackrf_usb.c
+++ b/firmware/hackrf_usb/hackrf_usb.c
@@ -187,6 +187,8 @@ static usb_request_handler_fn vendor_request_handler[] = {
 	usb_vendor_request_get_buffer_size,
 	usb_vendor_request_read_temperature,
 	usb_vendor_request_lock_radio_reg,
+	usb_vendor_request_open,
+	usb_vendor_request_close,
 };
 
 static const uint32_t vendor_request_handler_count =
diff --git a/firmware/hackrf_usb/usb_api_transceiver.c b/firmware/hackrf_usb/usb_api_transceiver.c
index e72a408b9..bb894bdcb 100644
--- a/firmware/hackrf_usb/usb_api_transceiver.c
+++ b/firmware/hackrf_usb/usb_api_transceiver.c
@@ -486,6 +486,42 @@ usb_request_status_t usb_vendor_request_get_buffer_size(
 	return USB_REQUEST_STATUS_OK;
 }
 
+usb_request_status_t usb_vendor_request_open(
+	usb_endpoint_t* const endpoint,
+	const usb_transfer_stage_t stage)
+{
+	uint16_t usb_api_version;
+	radio_config_mode_t radio_config_mode;
+
+	if (stage == USB_TRANSFER_STAGE_SETUP) {
+		usb_api_version = endpoint->setup.value;
+		radio_config_mode = (radio_config_mode_t) endpoint->setup.index;
+
+		// TODO let device know we have a new libhackrf connection and its supported usb_api_version
+		(void) usb_api_version;
+
+		// switch bitstreams and update radio mode
+		if (!radio_set_config_mode(&radio, radio_config_mode)) {
+			return USB_REQUEST_STATUS_STALL;
+		}
+		usb_transfer_schedule_ack(endpoint->in);
+	}
+
+	return USB_REQUEST_STATUS_OK;
+}
+
+usb_request_status_t usb_vendor_request_close(
+	usb_endpoint_t* const endpoint,
+	const usb_transfer_stage_t stage)
+{
+	if (stage == USB_TRANSFER_STAGE_SETUP) {
+		// TODO do nothing for now
+		usb_transfer_schedule_ack(endpoint->in);
+	}
+
+	return USB_REQUEST_STATUS_OK;
+}
+
 /* clang-format off */
 
 // Which GPDMA channel to use.
diff --git a/firmware/hackrf_usb/usb_api_transceiver.h b/firmware/hackrf_usb/usb_api_transceiver.h
index a29dec118..a28b8514e 100644
--- a/firmware/hackrf_usb/usb_api_transceiver.h
+++ b/firmware/hackrf_usb/usb_api_transceiver.h
@@ -80,6 +80,12 @@ usb_request_status_t usb_vendor_request_set_rx_overrun_limit(
 usb_request_status_t usb_vendor_request_get_buffer_size(
 	usb_endpoint_t* const endpoint,
 	const usb_transfer_stage_t stage);
+usb_request_status_t usb_vendor_request_open(
+	usb_endpoint_t* const endpoint,
+	const usb_transfer_stage_t stage);
+usb_request_status_t usb_vendor_request_close(
+	usb_endpoint_t* const endpoint,
+	const usb_transfer_stage_t stage);
 
 void request_transceiver_mode(transceiver_mode_t mode);
 void transceiver_startup(transceiver_mode_t mode);
diff --git a/host/libhackrf/src/hackrf.c b/host/libhackrf/src/hackrf.c
index 80e8d3196..4434aa9f5 100644
--- a/host/libhackrf/src/hackrf.c
+++ b/host/libhackrf/src/hackrf.c
@@ -123,6 +123,8 @@ typedef enum {
 	HACKRF_VENDOR_REQUEST_GET_BUFFER_SIZE = 61,
 	HACKRF_VENDOR_REQUEST_READ_TEMPERATURE = 62,
 	HACKRF_VENDOR_REQUEST_RADIO_LOCK_REG = 63,
+	HACKRF_VENDOR_REQUEST_OPEN = 64,
+	HACKRF_VENDOR_REQUEST_CLOSE = 65,
 } hackrf_vendor_request;
 
 #define USB_CONFIG_STANDARD 0x1
@@ -716,7 +718,10 @@ libusb_device_handle* hackrf_open_usb(const char* const desired_serial_number)
 	return usb_device;
 }
 
-static int hackrf_open_setup(libusb_device_handle* usb_device, hackrf_device** device)
+static int hackrf_open_setup(
+	enum radio_config_mode mode,
+	libusb_device_handle* usb_device,
+	hackrf_device** device)
 {
 	int result;
 	hackrf_device* lib_device;
@@ -798,6 +803,24 @@ static int hackrf_open_setup(libusb_device_handle* usb_device, hackrf_device** d
 		lib_device->buffer_size = 32768;
 	}
 
+	if (lib_device->usb_api_version >= 0x0114) {
+		// Send supported usb api version and requested configuration mode to device.
+		result = libusb_control_transfer(
+			lib_device->usb_device,
+			LIBUSB_ENDPOINT_OUT | LIBUSB_REQUEST_TYPE_VENDOR |
+				LIBUSB_RECIPIENT_DEVICE,
+			HACKRF_VENDOR_REQUEST_OPEN,
+			lib_device->usb_api_version,
+			(uint16_t) mode,
+			NULL,
+			0,
+			DEFAULT_REQUEST_TIMEOUT);
+		if (result != 0) {
+			last_libusb_error = result;
+			return HACKRF_ERROR_LIBUSB;
+		}
+	}
+
 	result = pthread_mutex_init(&lib_device->transfer_lock, NULL);
 	if (result != 0) {
 		free(lib_device);
@@ -836,7 +859,7 @@ static int hackrf_open_setup(libusb_device_handle* usb_device, hackrf_device** d
 	return HACKRF_SUCCESS;
 }
 
-int ADDCALL hackrf_open(hackrf_device** device)
+int ADDCALL hackrf_open_mode(const enum radio_config_mode mode, hackrf_device** device)
 {
 	libusb_device_handle* usb_device;
 
@@ -867,17 +890,18 @@ int ADDCALL hackrf_open(hackrf_device** device)
 		return HACKRF_ERROR_NOT_FOUND;
 	}
 
-	return hackrf_open_setup(usb_device, device);
+	return hackrf_open_setup(mode, usb_device, device);
 }
 
-int ADDCALL hackrf_open_by_serial(
+int ADDCALL hackrf_open_mode_by_serial(
+	const enum radio_config_mode mode,
 	const char* const desired_serial_number,
 	hackrf_device** device)
 {
 	libusb_device_handle* usb_device;
 
 	if (desired_serial_number == NULL) {
-		return hackrf_open(device);
+		return hackrf_open_mode(mode, device);
 	}
 
 	if (device == NULL) {
@@ -890,10 +914,11 @@ int ADDCALL hackrf_open_by_serial(
 		return HACKRF_ERROR_NOT_FOUND;
 	}
 
-	return hackrf_open_setup(usb_device, device);
+	return hackrf_open_setup(mode, usb_device, device);
 }
 
-int ADDCALL hackrf_device_list_open(
+int ADDCALL hackrf_device_list_open_mode(
+	const enum radio_config_mode mode,
 	hackrf_device_list_t* list,
 	int idx,
 	hackrf_device** device)
@@ -914,7 +939,30 @@ int ADDCALL hackrf_device_list_open(
 		return HACKRF_ERROR_LIBUSB;
 	}
 
-	return hackrf_open_setup(usb_device, device);
+	return hackrf_open_setup(mode, usb_device, device);
+}
+
+int ADDCALL hackrf_open(hackrf_device** device)
+{
+	return hackrf_open_mode(RADIO_CONFIG_STANDARD, device);
+}
+
+int ADDCALL hackrf_open_by_serial(
+	const char* const desired_serial_number,
+	hackrf_device** device)
+{
+	return hackrf_open_mode_by_serial(
+		RADIO_CONFIG_STANDARD,
+		desired_serial_number,
+		device);
+}
+
+int ADDCALL hackrf_device_list_open(
+	hackrf_device_list_t* list,
+	int idx,
+	hackrf_device** device)
+{
+	return hackrf_device_list_open_mode(RADIO_CONFIG_STANDARD, list, idx, device);
 }
 
 int ADDCALL hackrf_device_list_bus_sharing(hackrf_device_list_t* list, int idx)
@@ -2467,10 +2515,11 @@ int ADDCALL hackrf_stop_tx(hackrf_device* device)
 
 int ADDCALL hackrf_close(hackrf_device* device)
 {
-	int result1, result2;
+	int result1, result2, result3;
 
 	result1 = HACKRF_SUCCESS;
 	result2 = HACKRF_SUCCESS;
+	result3 = HACKRF_SUCCESS;
 
 	if (device != NULL) {
 		result1 = hackrf_stop_cmd(device);
@@ -2480,6 +2529,27 @@ int ADDCALL hackrf_close(hackrf_device* device)
 		 * also cancel any pending transmit/receive transfers.
 		 */
 		result2 = kill_transfer_thread(device);
+
+		if (device->usb_api_version >= 0x0114) {
+			/*
+			 * Let the device know it's been closed.
+			 */
+			result3 = libusb_control_transfer(
+				device->usb_device,
+				LIBUSB_ENDPOINT_OUT | LIBUSB_REQUEST_TYPE_VENDOR |
+					LIBUSB_RECIPIENT_DEVICE,
+				HACKRF_VENDOR_REQUEST_CLOSE,
+				0,
+				0,
+				NULL,
+				0,
+				DEFAULT_REQUEST_TIMEOUT);
+			if (result3 != 0) {
+				last_libusb_error = result3;
+				result3 = HACKRF_ERROR_LIBUSB;
+			}
+		}
+
 		if (device->usb_device != NULL) {
 			libusb_release_interface(device->usb_device, 0);
 			libusb_close(device->usb_device);
@@ -2498,7 +2568,12 @@ int ADDCALL hackrf_close(hackrf_device* device)
 	if (result2 != HACKRF_SUCCESS) {
 		return result2;
 	}
-	return result1;
+
+	if (result1 != HACKRF_SUCCESS) {
+		return result1;
+	}
+
+	return result3;
 }
 
 const char* ADDCALL hackrf_error_name(enum hackrf_error errcode)
diff --git a/host/libhackrf/src/hackrf.h b/host/libhackrf/src/hackrf.h
index e0c09cda4..c6524b28a 100644
--- a/host/libhackrf/src/hackrf.h
+++ b/host/libhackrf/src/hackrf.h
@@ -946,6 +946,19 @@ enum clkin_ctrl_signal {
 	CLKIN_SIGNAL_P22 = 1,
 };
 
+/**
+ * HackRF Pro Radio Configuration Mode.
+ *
+ * Used by @ref hackrf_open, @ref hackrf_open_mode_by_serial and @ref hackrf_device_list_open_mode to set the active configuration mode.
+ */
+enum radio_config_mode {
+	RADIO_CONFIG_LEGACY = 0,
+	RADIO_CONFIG_STANDARD = 1,
+	RADIO_CONFIG_EXT_PRECISION_RX = 2,
+	RADIO_CONFIG_EXT_PRECISION_TX = 3,
+	RADIO_CONFIG_HALF_PRECISION = 4,
+};
+
 /**
  * Opaque struct for hackrf device info. Object can be created via @ref hackrf_open, @ref hackrf_device_list_open or @ref hackrf_open_by_serial and be destroyed via @ref hackrf_close
  * @ingroup device
@@ -1199,6 +1212,7 @@ extern ADDAPI hackrf_device_list_t* ADDCALL hackrf_device_list();
 
 /**
  * Open a @ref hackrf_device from a device list
+ * @deprecated this function has been replaced by @ref hackrf_device_list_open_mode
  * @param[in] list device list to open device from
  * @param[in] idx index of the device to open
  * @param[out] device device handle to open
@@ -1210,6 +1224,24 @@ extern ADDAPI int ADDCALL hackrf_device_list_open(
 	int idx,
 	hackrf_device** device);
 
+/**
+ * Open a @ref hackrf_device from a device list and initialize it to the given radio configuration mode.
+ *
+ * Modes other than RADIO_CONFIG_STANDARD are only supported on HackRF Pro hardware.
+ *
+ * @param[in] mode configuration mode. Defaults to RADIO_CONFIG_STANDARD. Available modes are defined in @ref radio_config_mode.
+ * @param[in] list device list to open device from
+ * @param[in] idx index of the device to open
+ * @param[out] device device handle to open
+ * @return @ref HACKRF_SUCCESS on success, @ref HACKRF_ERROR_INVALID_PARAM on invalid parameters or other @ref hackrf_error variant
+ * @ingroup device
+ */
+extern ADDAPI int ADDCALL hackrf_device_list_open_mode(
+	const enum radio_config_mode mode,
+	hackrf_device_list_t* list,
+	int idx,
+	hackrf_device** device);
+
 /**
  * Check if a listed HackRF device is sharing its USB bus with other devices.
  *
@@ -1231,14 +1263,30 @@ extern ADDAPI void ADDCALL hackrf_device_list_free(hackrf_device_list_t* list);
 
 /**
  * Open first available HackRF device
+ * @deprecated this function has been replaced by @ref hackrf_open_mode
  * @param[out] device device handle
  * @return @ref HACKRF_SUCCESS on success, @ref HACKRF_ERROR_INVALID_PARAM if @p device is NULL, @ref HACKRF_ERROR_NOT_FOUND if no HackRF devices are found or other @ref hackrf_error variant
  * @ingroup device
  */
 extern ADDAPI int ADDCALL hackrf_open(hackrf_device** device);
 
+/**
+ * Open first available HackRF device and initialize it to the given radio configuration mode.
+ *
+ * Modes other than RADIO_CONFIG_STANDARD are only supported on HackRF Pro hardware.
+ *
+ * @param[in] mode configuration mode. Defaults to RADIO_CONFIG_STANDARD. Available modes are defined in @ref radio_config_mode.
+ * @param[out] device device handle
+ * @return @ref HACKRF_SUCCESS on success, @ref HACKRF_ERROR_INVALID_PARAM if @p device is NULL, @ref HACKRF_ERROR_NOT_FOUND if no HackRF devices are found or other @ref hackrf_error variant
+ * @ingroup device
+ */
+extern ADDAPI int ADDCALL hackrf_open_mode(
+	const enum radio_config_mode mode,
+	hackrf_device** device);
+
 /**
  * Open HackRF device by serial number
+ * @deprecated this function has been replaced by @ref hackrf_open_mode_by_serial
  * @param[in] desired_serial_number serial number of device to open. If NULL then default to first device found.
  * @param[out] device device handle
  * @return @ref HACKRF_SUCCESS on success, @ref HACKRF_ERROR_INVALID_PARAM if @p device is NULL, @ref HACKRF_ERROR_NOT_FOUND if no HackRF devices are found or other @ref hackrf_error variant
@@ -1248,6 +1296,22 @@ extern ADDAPI int ADDCALL hackrf_open_by_serial(
 	const char* const desired_serial_number,
 	hackrf_device** device);
 
+/**
+ * Open HackRF device by serial number and initialize it to the given radio configuration mode.
+ *
+ * Modes other than RADIO_CONFIG_STANDARD are only supported on HackRF Pro hardware.
+ *
+ * @param[in] mode configuration mode. Defaults to RADIO_CONFIG_STANDARD. Available modes are defined in @ref radio_config_mode.
+ * @param[in] desired_serial_number serial number of device to open. If NULL then default to first device found.
+ * @param[out] device device handle
+ * @return @ref HACKRF_SUCCESS on success, @ref HACKRF_ERROR_INVALID_PARAM if @p device is NULL, @ref HACKRF_ERROR_NOT_FOUND if no HackRF devices are found or other @ref hackrf_error variant
+ * @ingroup device
+ */
+extern ADDAPI int ADDCALL hackrf_open_mode_by_serial(
+	const enum radio_config_mode mode,
+	const char* const desired_serial_number,
+	hackrf_device** device);
+
 /**
  * Close a previously opened device
  * @param[in] device device to close

From 2d71aa1f0c032b7c9e6520582798fc02fb41475a Mon Sep 17 00:00:00 2001
From: Antoine van Gelder <antoine@greatscottgadgets.com>
Date: Wed, 24 Jun 2026 11:03:24 +0200
Subject: [PATCH 10/11] Add 'hackrf_radio_set_mode()'

---
 firmware/hackrf_usb/CMakeLists.txt  |  1 +
 firmware/hackrf_usb/hackrf_usb.c    |  2 ++
 firmware/hackrf_usb/usb_api_radio.c | 41 +++++++++++++++++++++++++++++
 firmware/hackrf_usb/usb_api_radio.h | 29 ++++++++++++++++++++
 host/libhackrf/src/hackrf.c         | 25 ++++++++++++++++++
 host/libhackrf/src/hackrf.h         | 12 +++++++++
 6 files changed, 110 insertions(+)
 create mode 100644 firmware/hackrf_usb/usb_api_radio.c
 create mode 100644 firmware/hackrf_usb/usb_api_radio.h

diff --git a/firmware/hackrf_usb/CMakeLists.txt b/firmware/hackrf_usb/CMakeLists.txt
index 871e0909f..027fc97a8 100644
--- a/firmware/hackrf_usb/CMakeLists.txt
+++ b/firmware/hackrf_usb/CMakeLists.txt
@@ -60,6 +60,7 @@ set(SRC_M4
 	usb_api_spiflash.c
 	usb_api_transceiver.c
 	usb_api_operacake.c
+	usb_api_radio.c
 	usb_api_sweep.c
 	usb_api_selftest.c
 	usb_api_ui.c
diff --git a/firmware/hackrf_usb/hackrf_usb.c b/firmware/hackrf_usb/hackrf_usb.c
index 5862048d0..c69f6dd75 100644
--- a/firmware/hackrf_usb/hackrf_usb.c
+++ b/firmware/hackrf_usb/hackrf_usb.c
@@ -75,6 +75,7 @@
 #include "usb_api_board_info.h"
 #include "usb_api_m0_state.h"
 #include "usb_api_operacake.h"
+#include "usb_api_radio.h"
 #include "usb_api_register.h"
 #include "usb_api_selftest.h"
 #include "usb_api_spiflash.h"
@@ -189,6 +190,7 @@ static usb_request_handler_fn vendor_request_handler[] = {
 	usb_vendor_request_lock_radio_reg,
 	usb_vendor_request_open,
 	usb_vendor_request_close,
+	usb_vendor_request_set_radio_mode,
 };
 
 static const uint32_t vendor_request_handler_count =
diff --git a/firmware/hackrf_usb/usb_api_radio.c b/firmware/hackrf_usb/usb_api_radio.c
new file mode 100644
index 000000000..e85c7d987
--- /dev/null
+++ b/firmware/hackrf_usb/usb_api_radio.c
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2026 Great Scott Gadgets <info@greatscottgadgets.com>
+ *
+ * This file is part of HackRF.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; see the file COPYING.  If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#include <radio.h>
+#include <usb_request.h>
+#include <usb_type.h>
+
+#include "usb_queue.h"
+
+usb_request_status_t usb_vendor_request_set_radio_mode(
+	usb_endpoint_t* const endpoint,
+	const usb_transfer_stage_t stage)
+{
+	if (stage == USB_TRANSFER_STAGE_SETUP) {
+		radio_config_mode_t mode = endpoint->setup.value;
+		if (!radio_set_config_mode(&radio, mode)) {
+			return USB_REQUEST_STATUS_STALL;
+		}
+		usb_transfer_schedule_ack(endpoint->in);
+	}
+
+	return USB_REQUEST_STATUS_OK;
+}
diff --git a/firmware/hackrf_usb/usb_api_radio.h b/firmware/hackrf_usb/usb_api_radio.h
new file mode 100644
index 000000000..9eb098d0d
--- /dev/null
+++ b/firmware/hackrf_usb/usb_api_radio.h
@@ -0,0 +1,29 @@
+/*
+ * Copyright 2026 Great Scott Gadgets <info@greatscottgadgets.com>
+ *
+ * This file is part of HackRF.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; see the file COPYING.  If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#pragma once
+
+#include <usb_request.h>
+#include <usb_type.h>
+
+usb_request_status_t usb_vendor_request_set_radio_mode(
+	usb_endpoint_t* const endpoint,
+	const usb_transfer_stage_t stage);
diff --git a/host/libhackrf/src/hackrf.c b/host/libhackrf/src/hackrf.c
index 4434aa9f5..9e740f100 100644
--- a/host/libhackrf/src/hackrf.c
+++ b/host/libhackrf/src/hackrf.c
@@ -125,6 +125,7 @@ typedef enum {
 	HACKRF_VENDOR_REQUEST_RADIO_LOCK_REG = 63,
 	HACKRF_VENDOR_REQUEST_OPEN = 64,
 	HACKRF_VENDOR_REQUEST_CLOSE = 65,
+	HACKRF_VENDOR_REQUEST_RADIO_SET_MODE = 66,
 } hackrf_vendor_request;
 
 #define USB_CONFIG_STANDARD 0x1
@@ -3701,6 +3702,30 @@ int ADDCALL hackrf_radio_lock_register(
 	return HACKRF_SUCCESS;
 }
 
+int ADDCALL hackrf_radio_set_mode(hackrf_device* device, const enum radio_config_mode mode)
+{
+	USB_API_REQUIRED(device, 0x0114);
+	int result;
+
+	result = libusb_control_transfer(
+		device->usb_device,
+		LIBUSB_ENDPOINT_OUT | LIBUSB_REQUEST_TYPE_VENDOR |
+			LIBUSB_RECIPIENT_DEVICE,
+		HACKRF_VENDOR_REQUEST_RADIO_SET_MODE,
+		mode,
+		0,
+		NULL,
+		0,
+		DEFAULT_REQUEST_TIMEOUT);
+
+	if (result != 0) {
+		last_libusb_error = result;
+		return HACKRF_ERROR_LIBUSB;
+	}
+
+	return HACKRF_SUCCESS;
+}
+
 #ifdef __cplusplus
 } // __cplusplus defined.
 #endif
diff --git a/host/libhackrf/src/hackrf.h b/host/libhackrf/src/hackrf.h
index c6524b28a..e3e730dae 100644
--- a/host/libhackrf/src/hackrf.h
+++ b/host/libhackrf/src/hackrf.h
@@ -2473,6 +2473,18 @@ extern ADDAPI int ADDCALL hackrf_radio_lock_register(
 	const uint8_t register_number,
 	const bool register_locked);
 
+/**
+ * Switches the radio configuration mode.
+ *
+ * @param[in] device device to configure
+ * @param[in] mode configuration mode. Defaults to RADIO_CONFIG_LEGACY. Available modes are defined in @ref radio_config_mode.
+ * @return @ref HACKRF_SUCCESS on success or @ref hackrf_error variant
+ * @ingroup configuration
+ */
+extern ADDAPI int ADDCALL hackrf_radio_set_mode(
+	hackrf_device* device,
+	const enum radio_config_mode mode);
+
 #ifdef __cplusplus
 } // __cplusplus defined.
 #endif

From 6bfe259812b2e2572f1b1ba56274fd1efaab47aa Mon Sep 17 00:00:00 2001
From: Antoine van Gelder <antoine@greatscottgadgets.com>
Date: Mon, 29 Jun 2026 15:03:12 +0200
Subject: [PATCH 11/11] Remove 'RADIO_CONFIG_LEGACY'

---
 firmware/common/radio.c     |  2 --
 firmware/common/radio.h     | 10 ++++------
 host/libhackrf/src/hackrf.h | 11 +++++------
 3 files changed, 9 insertions(+), 14 deletions(-)

diff --git a/firmware/common/radio.c b/firmware/common/radio.c
index 167d08340..33ef12db6 100644
--- a/firmware/common/radio.c
+++ b/firmware/common/radio.c
@@ -1040,7 +1040,6 @@ bool radio_set_config_mode(radio_t* const radio, const radio_config_mode_t mode)
 {
 	// Check if the requested mode is supported.
 	switch (mode) {
-	case RADIO_CONFIG_LEGACY:
 	case RADIO_CONFIG_STANDARD:
 		// supported on all boards
 		break;
@@ -1067,7 +1066,6 @@ bool radio_set_config_mode(radio_t* const radio, const radio_config_mode_t mode)
 	if (IS_PRALINE) {
 		fpga_bitstream_index_t bitstream_index;
 		switch (mode) {
-		case RADIO_CONFIG_LEGACY:
 		case RADIO_CONFIG_STANDARD:
 			bitstream_index = FPGA_BITSTREAM_STANDARD;
 			break;
diff --git a/firmware/common/radio.h b/firmware/common/radio.h
index 96ced41b6..2747cf974 100644
--- a/firmware/common/radio.h
+++ b/firmware/common/radio.h
@@ -41,14 +41,12 @@ typedef enum {
 } radio_error_t;
 
 /* radio configuration modes */
-// TODO are we sure we need a legacy mode?
 typedef enum {
-	RADIO_CONFIG_LEGACY = 0,
-	RADIO_CONFIG_STANDARD = 1,
+	RADIO_CONFIG_STANDARD = 0,
 #ifdef IS_PRALINE
-	RADIO_CONFIG_EXT_PRECISION_RX = 2,
-	RADIO_CONFIG_EXT_PRECISION_TX = 3,
-	RADIO_CONFIG_HALF_PRECISION = 4,
+	RADIO_CONFIG_EXT_PRECISION_RX = 1,
+	RADIO_CONFIG_EXT_PRECISION_TX = 2,
+	RADIO_CONFIG_HALF_PRECISION = 3,
 #endif
 } radio_config_mode_t;
 
diff --git a/host/libhackrf/src/hackrf.h b/host/libhackrf/src/hackrf.h
index e3e730dae..14c694088 100644
--- a/host/libhackrf/src/hackrf.h
+++ b/host/libhackrf/src/hackrf.h
@@ -952,11 +952,10 @@ enum clkin_ctrl_signal {
  * Used by @ref hackrf_open, @ref hackrf_open_mode_by_serial and @ref hackrf_device_list_open_mode to set the active configuration mode.
  */
 enum radio_config_mode {
-	RADIO_CONFIG_LEGACY = 0,
-	RADIO_CONFIG_STANDARD = 1,
-	RADIO_CONFIG_EXT_PRECISION_RX = 2,
-	RADIO_CONFIG_EXT_PRECISION_TX = 3,
-	RADIO_CONFIG_HALF_PRECISION = 4,
+	RADIO_CONFIG_STANDARD = 0,
+	RADIO_CONFIG_EXT_PRECISION_RX = 1,
+	RADIO_CONFIG_EXT_PRECISION_TX = 2,
+	RADIO_CONFIG_HALF_PRECISION = 3,
 };
 
 /**
@@ -2477,7 +2476,7 @@ extern ADDAPI int ADDCALL hackrf_radio_lock_register(
  * Switches the radio configuration mode.
  *
  * @param[in] device device to configure
- * @param[in] mode configuration mode. Defaults to RADIO_CONFIG_LEGACY. Available modes are defined in @ref radio_config_mode.
+ * @param[in] mode configuration mode. Defaults to RADIO_CONFIG_STANDARD. Available modes are defined in @ref radio_config_mode.
  * @return @ref HACKRF_SUCCESS on success or @ref hackrf_error variant
  * @ingroup configuration
  */