feat(machine/stm32): add STM32F401 and NUCLEO-F401RE support

[akif999]

1. Requirements

What was implemented

• Added support for the STM32F401RE board.
• Supported peripherals:
  • GPIO
  • UART
  • SPI
  • I2C
  • ADC
  • PWM
  • Arduino-compatible pin mapping (D0–D15, A0–A5)

What was NOT implemented in this PR

Item	Reason
USB OTG FS	NUCLEO-F401RE has no USB OTG connector. The chip-wide !stm32f401 exclude is kept for this board. It also blocks later F401 boards that have USB (for example Blackpill F401CC). Device files come from lib/stm32-svd, not lib/cmsis-svd.
crypto/rand (HW RNG)	STM32F401RE has no hardware RNG; crypto/rand panics with "no rng", consistent with TinyGo's behavior on other platforms without HW RNG; math/rand works normally
DAC, CAN, DCMI	Not present on STM32F401 silicon
blinky2	NUCLEO-F401RE has only one user LED (LD2); not applicable

Board Information

Board

Field	Details
Name	NUCLEO-F401RE
Developer / Manufacturer	STMicroelectronics
Schematic / User Manual	UM1724: STM32 Nucleo-64 boards (MB1136)
URL	https://www.st.com/en/evaluation-tools/nucleo-f401re.html

Chip

Field	Details
Chip Name	STM32F401RE
Architecture	Arm Cortex-M4F
Clock / Flash / RAM	84 MHz / 512 KB / 96 KB
Datasheet	STM32F401xD/xE Datasheet
Reference Manual	RM0368

2. Design

Already had comprehensive support for the STM32F4 family (F405/F407 via feather-stm32f405, stm32f4disco; F722/F469 for other NUCLEO/disco boards). These provided:

• A shared machine_stm32f4.go for GPIO, UART, SPI, I2C, ADC, and PWM drivers
• machine_stm32f40x_periph.go for F405/F407-specific peripherals (extra UARTs, TIMs, DAC, CAN, etc.)
• Template clock initialization in runtime/runtime_stm32f4.go

The STM32F401 shares the same Cortex-M4 core and peripheral bus architecture as the F405/F407, but has a reduced peripheral set and a lower maximum clock speed (84 MHz vs. 168 MHz). The following approach was taken:

1. New chip-level files

• targets/stm32f401.ld — linker script (512 KB Flash, 96 KB SRAM; no CCM region)
• src/machine/machine_stm32f401.go — CPU frequency (84 MHz), APB timer frequency constants
• src/machine/machine_stm32f4_pll_84mhz.go — PLL parameters for 84 MHz from 8 MHz HSE (M=4, N=168, P=4, Q=7; VCO=336 MHz)
• src/runtime/runtime_stm32f401.go — clock initialization (HSE → PLL → 84 MHz SYSCLK), TIM3 as the 1 kHz system tick timer (no CCM SRAM setup)
• src/device/stm32/stm32f401.go / stm32f401.s — generated from lib/stm32-svd (make/gen-device.mk)

2. Refactoring of machine_stm32f4.go

The shared machine_stm32f4.go contained getPort() (which referenced GPIO ports F–K, not present on F401) and enableAltFuncClock() (which referenced DAC, CAN1/2, TIM6/7/8/12/13/14, SDIO, USART3–6 — none of which exist on F401), as well as TIM6, TIM7, TIM8, TIM12, TIM13, TIM14 variable definitions. These were extracted out; the F405/F407/F469 versions remain under machine_stm32f40x_periph.go (positive tag stm32f405 || stm32f407 || stm32f469), and F401-specific versions are provided in machine_stm32f401_periph.go.

3. New F401-specific machine files

• src/machine/machine_stm32f401_periph.go (new) — F401-specific implementations of:
  • getPort(): GPIO ports A–E and H only (F401 does not have ports F, G, I–K)
  • enableAltFuncClock(): only the peripheral clocks present on F401
  • TIM, UART, SPI, I2C peripheral variable definitions scoped to F401

4. Shared F4 clock and ADC fixes

• APB1_FREQ / APB2_FREQ constants added alongside the existing timer frequencies in machine_stm32f401.go, machine_stm32f40x.go, and machine_stm32f469.go. SPI getBaudRate, I2C getFreqRange / getSpeed, and UART getBaudRateDivisor now use these so F401 does not run SPI/I2C/UART at 2× the requested clock.
• getBaudRateDivisor lives in the shared machine_stm32f4.go (not duplicated per chip).
• machine_stm32_adc_f4.go sample-time shift was wrong (ch * 6 and a left-associative <</* mix). It now uses 4 << (ch * 3) / 4 << ((ch - 10) * 3), which also compiles for F401 without a separate ADC file.

5. Peripheral availability via build tags

• machine_stm32f40x_periph.go — //go:build stm32f4 && (stm32f405 || stm32f407 || stm32f469) for the full F4 peripheral set
• machine_stm32_adc_f4.go — remains stm32f4 (shared with F401 after the sample-time fix)
• machine_stm32_otgfs_usb.go — changed from stm32f4 || stm32f7 to (stm32f4 && !stm32f401) || stm32f7. NUCLEO-F401RE has no USB OTG connector. This chip-wide exclude also blocks later F401 boards that have USB.
• machine_stm32f4_otgfs_vbus.go — removed stm32f401 from the build tag for the same reason
• usb.go — added !stm32f401 to the build tag for the same reason
• runtime/rand_hwrng.go — added !stm32f401 (no hardware RNG on F401)
• runtime/rand_norng.go and crypto/rand/rand_baremetal.go — include stm32f401 to route to the software RNG path

6. New board file

• src/machine/board_nucleof401re.go — LED, button, UART1/UART2, SPI0, I2C0, ADC aliases (A0–A5 / ADC0–ADC15), Arduino digital pin aliases (D0–D15)

7. Target JSON and examples

• targets/nucleo-f401re.json — inherits cortex-m4 (same soft-float / FPU-disabled setting as the other F4 targets), linker script, OpenOCD stlink interface, reset_config srst_only connect_assert_srst
• src/examples/pwm/nucleo-f401re.go — TIM2 on D6/D3 (TIM3 is the runtime tick timer)

8. Smoketest

• GNUmakefile — added nucleo-f401re target to make smoketest (after nucleo-f103rb)

3. Implementation

Please refer to Files changed on GitHub. Key files are listed below.

4. Testing

Environment

Item	Details
Host OS	Windows 11 (PowerShell / Git Bash)
TinyGo	Built from fork's dev branch
Flash tool	OpenOCD (xPack distribution, Windows)
Primary DUT	NUCLEO-F401RE (on-board ST-Link v2-1)
Peer board	Seeed XIAO RP2040

Functional Tests on NUCLEO-F401RE

Example / Test	Result	Notes
examples/blinky1	PASS	LD2 (PA5) blinks at 500 ms interval; interval change verified
examples/echo / echo2	PASS	UART1 / ST-Link VCP loopback echo works
examples/button	PASS	B1 (PC13) press toggles LD2; state printed via VCP
examples/pininterrupt	PASS	Edge interrupt on B1; naive software debounce behavior noted and expected
examples/device-id	PASS	96-bit chip UID printed via VCP
examples/rand (crypto/rand)	Expected	panic: no rng — F401RE has no HW RNG; consistent with TinyGo design
UART peer test (xiao-rp2040)	PASS	NUCLEO UART2 (PA9=TX/D8, PA10=RX/D2) ↔ xiao UART0 (D6=TX, D7=RX) at 115200 bps; echo confirmed
I2C master test (xiao-rp2040 as target)	PASS	I2C0 (PB8=SCL/D15, PB9=SDA/D14) master ↔ xiao I2C1 (D4/D5) target at 0x11; read/write/readback verified
SPI loopback test	PASS	SPI0 (PA5=SCK/D13, PA6=MISO/D12, PA7=MOSI/D11); MOSI→MISO jumper; tx == rx confirmed
examples/adc	PASS	A0 (PA0); ADC raw value changes with input voltage
examples/pwm	PASS	TIM2 CH3 (PB10=D6) and CH2 (PB3=D3); duty cycle sweep verified with oscilloscope

Regression Testing

• make smoketest executed on both the upstream dev branch and the fork branch
• All existing boards pass with identical results on both branches (including feather-stm32f405, stm32f4disco, nucleo-f103rb, nucleo-f722ze, pico, xiao-rp2040, and others)

[deadprogram]

Hello @akif999 thanks for the PR. Here are some editied comments from an assisted code review:

1. SPI and I2C run at 2X the requested clock on F401.

Suggested fix: add per-chip APB1_FREQ/APB2_FREQ constants alongside the existing APB1_TIM_FREQ/APB2_TIM_FREQ in machine_stm32f401.go, machine_stm32f40x.go, and machine_stm32f469.go, and use those in all four functions. That also lets getBaudRateDivisor stay in the shared file instead of being duplicated.

2. machine_stm32f401_adc.go can be dropped, if you fix the shared driver instead. Your version contains a real bug fix that should benefit all F4 parts. ADC_SMPR2_SMP1_Pos is 6, but the SMPx fields are 3 bits wide, so the existing 4 << (ch * 6) writes one field too high for every channel above 0. The SMPR1 line is worse — Go gives << and * equal precedence, left-associative, so 4 << (ch-10) * 6 parses as (4 << (ch-10)) * 6. Your cycles84 << (ch * 3) / << ((ch - 10) * 3) is correct. Since Cycles84 is just the literal 4, using 4 and 3 directly in machine_stm32_adc_f4.go compiles for F401 too, so you can delete the new file, drop the && !stm32f401 guard, and fix F405/F407/F469 in the process.

3. Missing example support files. examples/adc and examples/pwm don't build for this target:

adc → adc.go:11:32: undefined: machine.ADC2
pwm → pwm.go:67:20: undefined: pwm

To answer your question in the description: yes, please pull in src/examples/pwm/nucleo-f401re.go (see nucleo-f722ze.go for the pattern) and ADC0/ADC1/ADC2 aliases in the board file (as board_stm32f4disco.go has). Those make the results you reported reproducible. The rest of that commit can stay out.

Minor / optional:

• machine_stm32f4_extended.go: stm32f4 && !stm32f401 really means "F405/F407/F469" and will turn into a blacklist as F410/F411/F412 land — prefer a positive tag, like machine_stm32f4_pll_168mhz.go does. machine_stm32f40x_periph.go might also read better than "extended".
• runtime_stm32f401.go:66: RCC.CR.Set(HSEON) clobbers the whole register; SetBits is safer (runtime_stm32f7x2.go:94 does this, though runtime_stm32f405.go:77 has the same issue).
• initCLK applies PPRE1/PPRE2 after switching SW to PLL, so APB1 briefly runs at 84 MHz (2× its max). This mirrors runtime_stm32f405.go so it's pre-existing, but runtime_stm32f7x2.go:67-71 shows the safe ordering if you want to get it right in a new file.
• Build tags: machine_stm32f401.go uses stm32f4 && stm32f401 while the other three new files use bare stm32f401
• targets/nucleo-f401re.json uses 4-space indent; the rest of targets/ uses 2.
• Description says PLL M=8/N=336 but the code is M=4/N=168 (code is correct), and says fpu = fpv4-sp-d16 — cortex-m4.json actually sets +soft-float with FP disabled, same as the other F4 targets.

[akif999]

Hello @deadprogram thanks for the review — I’ve addressed the comments.

Required

Added per-chip APB1_FREQ / APB2_FREQ next to the existing timer constants, and switched SPI getBaudRate, I2C getFreqRange / getSpeed, and UART getBaudRateDivisor to use them. getBaudRateDivisor now lives in the shared F4 file instead of being duplicated.
Fixed the sample-time shifts in machine_stm32_adc_f4.go (4 << (ch * 3) / 4 << ((ch - 10) * 3)), dropped the !stm32f401 guard, and removed machine_stm32f401_adc.go.
Added ADC0–ADC15 aliases on the board file and src/examples/pwm/nucleo-f401re.go (TIM2 on D6/D3, since TIM3 is the tick timer) so examples/adc and examples/pwm build for this target.

Optional / minor

machine_stm32f401.go now uses a bare stm32f401 build tag.
The full-peripheral F4 file uses a positive tag (stm32f405 || stm32f407 || stm32f469) and was renamed to machine_stm32f40x_periph.go to match machine_stm32f401_periph.go.
HSE is enabled with SetBits, and APB prescalers are applied before switching SYSCLK to PLL.
targets/nucleo-f401re.json is indented with 2 spaces.
I also rebased onto current dev after the smoketest move (#5616). The nucleo-f401re blinky1 entry now lives in make/smoketest.mk.

Happy to adjust anything further.

[akif999]

I will check failure of Actions.

[akif999]

I will check failure of Actions.
I fixed.

[deadprogram]

Thanks @akif999. I checked out the PR head (a4e60866), generated the device files, and built with a local toolchain. Here are the results of a second assisted review.

All the earlier points are fixed and verified.

There are 2 new items, both minor:

1. initRNG() in machine_stm32f401_periph.go is dead code. The only caller is machine_stm32_rng.go, and that file now excludes stm32f401. Did you mean to actually connect this up somehow?

2. The USB OTG FS exclusion does not reproduce. make/gen-device.mk generates the device files from lib/stm32-svd, not from lib/cmsis-svd as the description says.

NUCLEO-F401RE has no OTG connector, so it is acceptable to keep the exclusion for that. But the three chip-wide !stm32f401 blacklists will block a future F401 board that does have USB, such as the Blackpill F401CC. Perhaps correct the reason in the comments and the description?

Notes

• The ADC0-ADC15 table follows board_stm32f4disco.go, so ADC2 is PA2, which is the ST-Link VCP TX pin. The unmodified examples/adc uses machine.ADC2, so it builds, but the console output stops when the pin becomes an analog input. This behavior is the same on f4disco, so it is not new. A short comment that points users to A0 would help.
• Optional: add nucleo-f401re to the examples/pwm line in make/smoketest.mk, next to stm32f4disco-1, to keep the new example file in the build.

[akif999]

@deadprogram Thanks for the second review.

initRNG() in machine_stm32f401_periph.go is dead code. The only caller is machine_stm32_rng.go, and that file now excludes stm32f401. Did you mean to actually connect this up somehow?

initRNG() was only a leftover stub. I did not intend to wire up RNG on F401 (the chip has no hardware RNG). So, I removed the unused function.

The USB OTG FS exclusion does not reproduce. make/gen-device.mk generates the device files from lib/stm32-svd, not from lib/cmsis-svd as the description says.

You are right about USB. Device files come from lib/stm32-svd, and the earlier “register names do not match” reason was wrong. I kept the chip-wide !stm32f401 exclude because NUCLEO-F401RE has no OTG connector. I updated the comments in usb.go / machine_stm32_otgfs_usb.go and the PR description to say that. The description now also says device files are generated from lib/stm32-svd via make/gen-device.mk, not from lib/cmsis-svd. I noted that this chip-wide exclude will block later F401 boards that do have USB, such as the Blackpill F401CC.

The ADC0-ADC15 table follows board_stm32f4disco.go, so ADC2 is PA2, which is the ST-Link VCP TX pin. The unmodified examples/adc uses machine.ADC2, so it builds, but the console output stops when the pin becomes an analog input. This behavior is the same on f4disco, so it is not new. A short comment that points users to A0 would help.

I added a short comment on the ADC aliases. examples/adc uses ADC2 (PA2 / ST-Link VCP TX), so users should use A0 instead.

Optional: add nucleo-f401re to the examples/pwm line in make/smoketest.mk, next to stm32f4disco-1, to keep the new example file in the build.

I added nucleo-f401re examples/pwm to make/smoketest.mk, next to stm32f4disco-1.

The GitHub PR body is updated to match these comments.