feat: add core register read and write functions

Author: ckrenslehner

stm32cubeprogrammer-sys/include/CubeProgrammer_API_Undocumented.h

@@ -0,0 +1,39 @@
+/**
+ * @brief Undocumented API functions for STM32CubeProgrammer
+ * Credits to: https://github.com/wervin/stm32cubeprog-rs
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdint.h>
+#include "DeviceDataStructure.h"
+
+#if (defined WIN32 || defined _WIN32 || defined WINCE)
+# define CP_EXPORTS __declspec(dllexport)
+#else
+# define CP_EXPORTS
+#endif
+
+/**
+ * \brief Write a core register.
+ * \param register : The register to write.
+ * \param data     : The data to write.
+ * \return 0 if the writing operation correctly finished, otherwise an error occurred.
+ */
+int writeCoreRegister(unsigned int register, unsigned int data);
+
+/**
+ * \brief Read a core register.
+ * \param register : The register to read.
+ * \param data     : The data read.
+ * \return 0 if the reading operation correctly finished, otherwise an error occurred.
+ */
+int readCoreRegister(unsigned int register, unsigned int *data);
+
+#ifdef __cplusplus
+}
+#endif

stm32cubeprogrammer-sys/include/wrapper.h

@@ -0,0 +1,3 @@
+// Bindgen wrapper
+#include "CubeProgrammer_API.h"
+#include "CubeProgrammer_API_Undocumented.h"

stm32cubeprogrammer-sys/justfile

@@ -1,4 +1,13 @@
-bindgen_header := "include/CubeProgrammer_API.h"
+# Nushell needs to be installeds
+set shell := ["nu", "-c"]
+
+shebang := if os() == 'windows' {
+  'nu.exe'
+} else {
+  '/usr/bin/env nu'
+}
+
+bindgen_header := "include/wrapper.h"
 
 bindgen_output := if os() == 'windows' {
   "src/bindings_windows.rs"
@@ -8,4 +17,4 @@ bindgen_output := if os() == 'windows' {
 
 # Generate bindings for the CubeProgrammer API dynamic library
 generate-bindings:
-    bindgen {{source_directory()}}/{{bindgen_header}} --dynamic-loading CubeProgrammer_API --output {{source_directory()}}/{{bindgen_output}} -- -x c++
+    bindgen {{source_directory()}}/{{bindgen_header}} --dynamic-loading CubeProgrammer_API --output {{source_directory()}}/{{bindgen_output}} -- -x c++ -target x86_64-pc-windows-msvc

stm32cubeprogrammer-sys/src/bindings_windows.rs

@@ -1,4 +1,4 @@
-/* automatically generated by rust-bindgen 0.70.1 */
+/* automatically generated by rust-bindgen 0.71.1 */
 
 pub const _VCRT_COMPILER_PREPROCESSOR: u32 = 1;
 pub const _SAL_VERSION: u32 = 20;
@@ -1240,6 +1240,20 @@ pub struct CubeProgrammer_API {
         ) -> ::std::os::raw::c_int,
         ::libloading::Error,
     >,
+    pub writeCoreRegister: Result<
+        unsafe extern "C" fn(
+            arg1: ::std::os::raw::c_uint,
+            data: ::std::os::raw::c_uint,
+        ) -> ::std::os::raw::c_int,
+        ::libloading::Error,
+    >,
+    pub readCoreRegister: Result<
+        unsafe extern "C" fn(
+            arg1: ::std::os::raw::c_uint,
+            data: *mut ::std::os::raw::c_uint,
+        ) -> ::std::os::raw::c_int,
+        ::libloading::Error,
+    >,
 }
 impl CubeProgrammer_API {
     pub unsafe fn new<P>(path: P) -> Result<Self, ::libloading::Error>
@@ -1331,6 +1345,8 @@ impl CubeProgrammer_API {
         let getHsmVersion = __library.get(b"getHsmVersion\0").map(|sym| *sym);
         let getHsmType = __library.get(b"getHsmType\0").map(|sym| *sym);
         let getHsmLicense = __library.get(b"getHsmLicense\0").map(|sym| *sym);
+        let writeCoreRegister = __library.get(b"writeCoreRegister\0").map(|sym| *sym);
+        let readCoreRegister = __library.get(b"readCoreRegister\0").map(|sym| *sym);
         Ok(CubeProgrammer_API {
             __library,
             __va_start,
@@ -1404,6 +1420,8 @@ impl CubeProgrammer_API {
             getHsmVersion,
             getHsmType,
             getHsmLicense,
+            writeCoreRegister,
+            readCoreRegister,
         })
     }
     pub unsafe fn __security_init_cookie(&self) {
@@ -2074,4 +2092,26 @@ impl CubeProgrammer_API {
             .as_ref()
             .expect("Expected function, got error."))(hsmSlotId, outLicensePath)
     }
+    #[doc = " \\brief Write a core register.\n \\param register : The register to write.\n \\param data     : The data to write.\n \\return 0 if the writing operation correctly finished, otherwise an error occurred."]
+    pub unsafe fn writeCoreRegister(
+        &self,
+        arg1: ::std::os::raw::c_uint,
+        data: ::std::os::raw::c_uint,
+    ) -> ::std::os::raw::c_int {
+        (self
+            .writeCoreRegister
+            .as_ref()
+            .expect("Expected function, got error."))(arg1, data)
+    }
+    #[doc = " \\brief Read a core register.\n \\param register : The register to read.\n \\param data     : The data read.\n \\return 0 if the reading operation correctly finished, otherwise an error occurred."]
+    pub unsafe fn readCoreRegister(
+        &self,
+        arg1: ::std::os::raw::c_uint,
+        data: *mut ::std::os::raw::c_uint,
+    ) -> ::std::os::raw::c_int {
+        (self
+            .readCoreRegister
+            .as_ref()
+            .expect("Expected function, got error."))(arg1, data)
+    }
 }

stm32cubeprogrammer/src/api_types.rs

@@ -28,6 +28,31 @@ pub enum ErrorCode {
     UnknownError = -17,
 }
 
+/// CoreRegister of the target
+#[derive(Debug, Copy, Clone, strum::Display, IntoPrimitive, FromPrimitive)]
+#[repr(u32)]
+pub enum CoreRegister {
+    R0 = 0,
+    R1,
+    R2,
+    R3,
+    R4,
+    R5,
+    R6,
+    R7,
+    R8,
+    R9,
+    R10,
+    R11,
+    R12,
+    SP,
+    LR,
+    PC,
+
+    #[num_enum(catch_all)]
+    Unknown(u32),
+}
+
 /// Return code which is mapped to an error if it is not equal to SUCCESS
 /// Sometimes success is 0, sometimes it is 1
 #[derive(Debug, From, Into)]

stm32cubeprogrammer/src/cube_programmer.rs

@@ -733,6 +733,30 @@ impl ConnectedProgrammer<'_> {
         api_types::ReturnCode::<1>::from(unsafe { self.api().startWirelessStack() })
             .check(crate::error::Action::StartWirelessStack)
     }
+
+    /// Write [`crate::api_types::CoreRegister`]
+    pub fn write_core_register(&self, register: crate::api_types::CoreRegister, value: u32) -> CubeProgrammerResult<()> {
+        self.check_connection()?;
+
+        api_types::ReturnCode::<0>::from(unsafe {
+            self.api().writeCoreRegister(register.into(), value)
+        })
+        .check(crate::error::Action::WriteCoreRegister)
+    }
+
+    /// Read [`crate::api_types::CoreRegister`]
+    pub fn read_core_register(&self, register: crate::api_types::CoreRegister) -> CubeProgrammerResult<u32> {
+        self.check_connection()?;
+
+        let mut value = 0;
+
+        api_types::ReturnCode::<0>::from(unsafe {
+            self.api().readCoreRegister(register.into(), &mut value)
+        })
+        .check(crate::error::Action::ReadCoreRegister)?;
+
+        Ok(value)
+    }
 }
 
 impl ConnectedFusProgrammer<'_> {

stm32cubeprogrammer/src/error.rs

@@ -31,6 +31,8 @@ pub enum Action {
     DeleteWirelessStack,
     StartWirelessStack,
     ListConnectedProbes,
+    WriteCoreRegister,
+    ReadCoreRegister,
 }
 
 #[derive(Debug, Error, Display)]

stm32cubeprogrammer/src/lib.rs

@@ -4,7 +4,7 @@
 //! ```no_run
 //! use stm32cubeprogrammer::{
 //!     probe::{ConnectionParameters, Protocol, ResetMode},
-//!     CubeProgrammer,
+//!     CubeProgrammer, CoreRegister
 //! };
 //!
 //! // You need to supply the path to the root directory of the STM32CubeProgrammer installation
@@ -28,6 +28,11 @@
 //!     .expect("Failed to connect to target");
 //!
 //! println!("Target information: {}", connected.target_information());
+//! 
+//! connected.write_core_register(CoreRegister::R0, 0x12345678).expect("Failed to write core register");
+//! 
+//! let r0 = connected.read_core_register(CoreRegister::R0).expect("Failed to read core register");
+//! println!("R0: 0x{:08X}", r0);
 //!
 //! // If there are multiple connected probes with a target, you can establish multiple connections simultaneously
 //! let connected_other = programmer
@@ -56,6 +61,7 @@
 //! - Downloading files as hex or bin
 //! - Reading and writing memory
 //!     - Uses the [`bytemuck::Pod`](https://docs.rs/bytemuck/1.21.0/bytemuck/trait.Pod.html) trait for reading and writing data from/to memory
+//! - Reading and writing of core registers
 //! - Resetting the target
 //! - Enabling and disabling readout protection (Level B)
 //! - Reset target
@@ -85,12 +91,11 @@
 //!
 //! # Warranty
 //! This crate is supplied as is without any warranty. Use at your own risk.
-
 pub mod api_log;
 pub use api_log::{LogMessageType, Verbosity};
 
 pub mod api_types;
-pub use api_types::{fus, probe, TargetInformation};
+pub use api_types::{fus, probe, TargetInformation, CoreRegister};
 
 pub mod display;
 pub use display::DisplayCallback;