bmputil 1.1.0

Black Magic Probe companion utility
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

// SPDX-License-Identifier: MIT OR Apache-2.0
// SPDX-FileCopyrightText: 2022-2025 1BitSquared <info@1bitsquared.com>
// SPDX-FileContributor: Written by Mikaela Szekely <mikaela.szekely@qyriad.me>
// SPDX-FileContributor: Modified by Rachel Mant <git@dragonmux.network>

use std::array::TryFromSliceError;
use std::fmt::Display;

use clap::ValueEnum;
use clap::builder::PossibleValue;
use color_eyre::eyre::{Context, Result, eyre};
use log::debug;

use crate::bmp::BmpPlatform;
use crate::firmware_file::FirmwareFile;

/// Represents a conceptual Vector Table for Armv7 processors.
pub struct Armv7mVectorTable<'b>
{
	bytes: &'b [u8],
}

impl<'b> Armv7mVectorTable<'b>
{
	fn word(&self, index: usize) -> Result<u32, TryFromSliceError>
	{
		let start = index * 4;
		let array: [u8; 4] = self.bytes[(start)..(start + 4)].try_into()?;

		Ok(u32::from_le_bytes(array))
	}

	/// Construct a conceptual Armv7m Vector Table from a bytes slice.
	pub fn from_bytes(bytes: &'b [u8]) -> Self
	{
		if bytes.len() < (4 * 2) {
			panic!("Data passed is not long enough for an Armv7m Vector Table!");
		}

		Self {
			bytes,
		}
	}

	pub fn stack_pointer(&self) -> Result<u32, TryFromSliceError>
	{
		self.word(0)
	}

	pub fn reset_vector(&self) -> Result<u32, TryFromSliceError>
	{
		self.word(1)
	}

	pub fn exception(&self, exception_number: u32) -> Result<u32, TryFromSliceError>
	{
		self.word((exception_number + 1) as usize)
	}
}

/// Firmware types for the Black Magic Probe.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
pub enum FirmwareType
{
	/// The bootloader. For native probes this is linked at 0x0800_0000
	Bootloader,
	/// The main application. For native probes this is linked at 0x0800_2000.
	Application,
}

impl FirmwareType
{
	/// Detect the kind of firmware from the given binary by examining its reset vector address.
	///
	/// This function panics if `firmware.len() < 8`.
	pub fn detect_from_firmware(platform: BmpPlatform, firmware_file: &FirmwareFile) -> Result<Self>
	{
		// If the firmware image has a load address
		if let Some(load_address) = firmware_file.load_address() {
			// Check if the address is the bootloader area for the platform
			let boot_start = platform.load_address(Self::Bootloader);
			return Ok(if load_address == boot_start {
				Self::Bootloader
			} else {
				Self::Application
			});
		}

		// If the firmware doesn't have a known load address, fall back to figuring it out
		// from the NVIC table at the front of the image
		let buffer = &firmware_file.data()[0..(4 * 2)];

		let vector_table = Armv7mVectorTable::from_bytes(buffer);
		let reset_vector = vector_table
			.reset_vector()
			.wrap_err("Firmware file does not seem valid: vector table too short")?;

		debug!("Detected reset vector in firmware file: 0x{:08x}", reset_vector);

		// Sanity check.
		if (reset_vector & 0x0800_0000) != 0x0800_0000 {
			return Err(eyre!(
				"Firmware file does not seem valid: reset vector address seems to be outside of reasonable bounds - \
				 0x{:08x}",
				reset_vector
			));
		}

		let app_start = platform.load_address(Self::Application);

		if reset_vector > app_start {
			Ok(Self::Application)
		} else {
			Ok(Self::Bootloader)
		}
	}
}

impl Display for FirmwareType
{
	fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result
	{
		match self {
			Self::Bootloader => write!(f, "bootloader")?,
			Self::Application => write!(f, "application")?,
		};

		Ok(())
	}
}

impl ValueEnum for FirmwareType
{
	fn value_variants<'a>() -> &'a [Self]
	{
		&[Self::Application, Self::Bootloader]
	}

	fn to_possible_value(&self) -> Option<PossibleValue>
	{
		match self {
			Self::Bootloader => Some("bootloader".into()),
			Self::Application => Some("application".into()),
		}
	}
}