From 6b752dcfaf93be0390010a17f0162206a222ba45 Mon Sep 17 00:00:00 2001
From: Clemens Elflein <clemens1@familie-elflein.de>
Date: Tue, 17 Dec 2024 22:05:24 +0100
Subject: [PATCH] Added CM4 Flashing Tutorial

---
 content/en/docs/Tutorials/_index.md           |  8 ++
 .../flashing-stm32-from-cm4/_index.md         | 33 +++++++++
 static/downloads/openocd-xcore.cfg            | 74 +++++++++++++++++++
 3 files changed, 115 insertions(+)
 create mode 100644 content/en/docs/Tutorials/_index.md
 create mode 100644 content/en/docs/Tutorials/flashing-stm32-from-cm4/_index.md
 create mode 100644 static/downloads/openocd-xcore.cfg

diff --git a/content/en/docs/Tutorials/_index.md b/content/en/docs/Tutorials/_index.md
new file mode 100644
index 0000000..afc8f88
--- /dev/null
+++ b/content/en/docs/Tutorials/_index.md
@@ -0,0 +1,8 @@
+---
+title: "Tutorials"
+linkTitle: "Tutorials"
+weight: 99
+description: Tutorials to help you getting started
+---
+
+This page is a growing collection of tutorials for common tasks with the xCore hardware.
diff --git a/content/en/docs/Tutorials/flashing-stm32-from-cm4/_index.md b/content/en/docs/Tutorials/flashing-stm32-from-cm4/_index.md
new file mode 100644
index 0000000..5bde2f6
--- /dev/null
+++ b/content/en/docs/Tutorials/flashing-stm32-from-cm4/_index.md
@@ -0,0 +1,33 @@
+---
+title: "Flashing STM32 From CM4"
+linkTitle: "Flashing STM32 From CM4"
+description: Tutorial for flashing the STM32 microcontroller from the Raspberry Pi CM4.
+---
+
+In order to use the Raspberry Pi CM4 to upload firmware to the STM32, we need a custom version of OpenOCD which can use
+the CM4's GPIOs to connect to the STM32's SWD interface.
+
+### Step 1: Building OpenOCD
+Execute the following commands in order to install the dependencies, build and install OpenOCD:
+```bash
+sudo apt install automake autoconf build-essential libtool libftdi-dev libusb-1.0-0-dev texinfo pkg-config rpi.gpio-common curl
+git clone https://github.com/raspberrypi/openocd.git --recursive
+cd openocd
+./bootstrap
+./configure --enable-ftdi --enable-sysfsgpio --enable-bcm2835gpio
+make -j$(nproc)
+sudo make install
+```
+
+### Step 2: Get the OpenOCD Configuration
+Fetch the configuration and install it globally for OpenOCD to find it:
+```bash
+sudo curl -o /usr/local/share/openocd/scripts/interface/xcore.cfg https://core.x-tech.online/downloads/openocd-xcore.cfg
+```
+
+### Step 3: Upload a binary
+Get a binary (.elf format) and upload it to the STM32 like this:
+```bash
+openocd -f interface/xcore.cfg -f target/stm32h7x.cfg -c "program your-binary.elf verify reset exit"
+```
+The firmware should be uploaded and the program should be running.
diff --git a/static/downloads/openocd-xcore.cfg b/static/downloads/openocd-xcore.cfg
new file mode 100644
index 0000000..3154630
--- /dev/null
+++ b/static/downloads/openocd-xcore.cfg
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+# Config for Raspberry Pi used as a bitbang adapter.
+# https://www.raspberrypi.com/documentation/computers/raspberry-pi.html
+
+# Supports all models with 40-pin or 26-pin GPIO connector up to Raspberry Pi 4 B
+# also supports Raspberry Pi Zero, Zero W and Zero 2 W.
+
+# Adapter speed calibration is computed from cpufreq/scaling_max_freq.
+# Adjusts automatically if CPU is overclocked.
+
+adapter driver bcm2835gpio
+
+proc read_file { name } {
+	if {[catch {open $name r} fd]} {
+		return ""
+	}
+	set result [read $fd]
+	close $fd
+	return $result
+}
+
+proc measure_clock {} {
+	set result [exec vcgencmd measure_clock arm]
+	set clock_hz [lindex [split $result "="] 1]
+	expr { $clock_hz / 1000 }
+}
+
+proc get_max_cpu_clock { default } {
+	set clock [read_file /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq]
+	if { $clock > 100000 } {
+		return $clock
+	}
+
+	# cpufreq not available. As the last resort try Broadcom's proprietary utility
+	if {![catch measure_clock clock] && $clock > 100000} {
+		return $clock
+	}
+
+	echo "WARNING: Host CPU clock unknown."
+	echo "WARNING: Using the highest possible value $default kHz as a safe default."
+	echo "WARNING: Expect JTAG/SWD clock significantly slower than requested."
+
+	return $default
+}
+
+set compat [read_file /proc/device-tree/compatible]
+set clocks_per_timing_loop 4
+
+if {[string match *bcm2711* $compat]} {
+	set speed_offset 52
+} elseif {[string match *bcm2837* $compat] || [string match *bcm2710* $compat]} {
+	set speed_offset 34
+} elseif {[string match *bcm2836* $compat] || [string match *bcm2709* $compat]} {
+	set speed_offset 36
+} elseif {[string match *bcm2835* $compat] || [string match *bcm2708* $compat]} {
+	set clocks_per_timing_loop 6
+	set speed_offset 32
+} else {
+	set speed_offset 32
+	echo "WARNING: Unknown type of the host SoC. Expect JTAG/SWD clock slower than requested."
+}
+
+set clock [get_max_cpu_clock 2000000]
+set speed_coeff [expr { $clock / $clocks_per_timing_loop }]
+
+# Transition delay calculation: SPEED_COEFF/khz - SPEED_OFFSET
+# The coefficients depend on system clock and CPU frequency scaling.
+bcm2835gpio speed_coeffs $speed_coeff $speed_offset
+
+transport select swd
+adapter gpio swclk -chip 0 27
+adapter gpio swdio -chip 0 22
+