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
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
//! The Instrumentation Trace Macrocell.
//!
//! This module provides interface to transmit log data through the SWO pin.
//!
//! ITM ports #0 and #1 are reserved for STDOUT and STDERR respectively.

#![cfg_attr(feature = "std", allow(unreachable_code, unused_variables))]

mod macros;
mod port;

/// Updates the SWO prescaler register to match the baud-rate defined at
/// `Drone.toml`.
#[doc(inline)]
pub use drone_cortex_m_macros::itm_update_prescaler as update_prescaler;

pub use self::port::Port;

use crate::{
    map::reg::{dwt, itm, tpiu},
    processor,
    reg::prelude::*,
};
use core::{
    alloc::Layout,
    fmt::{self, Write},
    ptr::read_volatile,
};
use drone_core::{heap::Pool, token::Token};

/// Port number of the standard output stream.
pub const STDOUT_PORT: usize = 0;

/// Port number of the standard error stream.
pub const STDERR_PORT: usize = 1;

/// Port number of the heap trace stream.
pub const HEAP_TRACE_PORT: usize = 31;

/// XOR pattern for heap trace output.
pub const HEAP_TRACE_KEY: u32 = 0xC5AC_CE55;

const ITM_TER: usize = 0xE000_0E00;
const ITM_TCR: usize = 0xE000_0E80;

/// Returns `true` if a debug probe is connected and listening to the ITM
/// output.
#[inline]
pub fn is_enabled() -> bool {
    #[cfg(feature = "std")]
    return false;
    unsafe { read_volatile(ITM_TCR as *const u32) & 1 != 0 }
}

/// Returns `true` if a debug probe is connected and listening to the ITM port
/// `port` output.
#[inline]
pub fn is_port_enabled(port: usize) -> bool {
    #[cfg(feature = "std")]
    return false;
    unsafe { read_volatile(ITM_TER as *const u32) & 1 << port != 0 }
}

/// Writes `string` to the stimulus port number `address`.
///
/// The presence of a debug probe is not checked, so it is recommended to use it
/// together with [`is_port_enabled`].
///
/// # Examples
///
/// ```
/// use drone_cortex_m::itm;
///
/// if itm::is_port_enabled(11) {
///     itm::write_str(11, "hello there!\n");
/// }
/// ```
#[inline(never)]
pub fn write_str(address: usize, string: &str) {
    // Can never be `Err(_)`
    Port::new(address).write_str(string).unwrap_or(())
}

/// Writes `args` to the stimulus port number `address`.
///
/// The presence of a debug probe is not checked, so it is recommended to use it
/// together with [`is_port_enabled`].
///
/// # Examples
///
/// ```
/// use drone_cortex_m::itm;
///
/// let a = 0;
///
/// if itm::is_port_enabled(11) {
///     itm::write_fmt(11, format_args!("a = {}\n", a));
/// }
/// ```
#[inline(never)]
pub fn write_fmt(address: usize, args: fmt::Arguments<'_>) {
    // Can never be `Err(_)`
    Port::new(address).write_fmt(args).unwrap_or(())
}

/// Blocks until all pending packets are transmitted.
///
/// This function is a no-op if no debug probe is connected and listening.
#[inline(always)]
pub fn flush() {
    #[inline(never)]
    fn flush() {
        let tcr = unsafe { itm::Tcr::<Urt>::take() };
        while tcr.load().busy() {}
        let acpr = unsafe { tpiu::Acpr::<Urt>::take() };
        processor::spin(acpr.load().swoscaler() * 64);
    }
    if is_enabled() {
        flush();
    }
}

/// Generates an ITM synchronization packet.
#[inline]
pub fn sync() {
    let mut cyccnt = unsafe { dwt::Cyccnt::<Urt>::take() };
    cyccnt.store(|r| r.write_cyccnt(0xFFFF_FFFF));
}

/// Updates the SWO prescaler register.
#[inline]
pub fn update_prescaler(swoscaler: u32) {
    let mut acpr = unsafe { tpiu::Acpr::<Urt>::take() };
    acpr.store(|r| r.write_swoscaler(swoscaler));
    sync();
}

/// Logs an allocation to the ITM port #31.
///
/// This function is a no-op if no debug probe is connected and listening.
#[inline(always)]
pub fn trace_alloc(layout: Layout, _pool: &Pool) {
    #[inline(never)]
    fn instrument(layout: Layout) {
        #[cfg(feature = "std")]
        return unimplemented!();
        unsafe { asm!("cpsid i" :::: "volatile") };
        Port::new(HEAP_TRACE_PORT)
            .write(0xCDAB_u16)
            .write((layout.size() as u32) ^ HEAP_TRACE_KEY);
        unsafe { asm!("cpsie i" :::: "volatile") };
    }
    if is_port_enabled(HEAP_TRACE_PORT) {
        instrument(layout);
    }
}

/// Logs a deallocation to the ITM port #31.
///
/// This function is a no-op if no debug probe is connected and listening.
#[inline(always)]
pub fn trace_dealloc(layout: Layout, _pool: &Pool) {
    #[inline(never)]
    fn instrument(layout: Layout) {
        #[cfg(feature = "std")]
        return unimplemented!();
        unsafe { asm!("cpsid i" :::: "volatile") };
        Port::new(HEAP_TRACE_PORT)
            .write(0xBADC_u16)
            .write((layout.size() as u32) ^ HEAP_TRACE_KEY);
        unsafe { asm!("cpsie i" :::: "volatile") };
    }
    if is_port_enabled(HEAP_TRACE_PORT) {
        instrument(layout);
    }
}

/// Logs growing in place to the ITM port #31.
///
/// This function is a no-op if no debug probe is connected and listening.
#[inline(always)]
pub fn trace_grow_in_place(layout: Layout, new_size: usize) {
    #[inline(never)]
    fn instrument(layout: Layout, new_size: usize) {
        #[cfg(feature = "std")]
        return unimplemented!();
        unsafe { asm!("cpsid i" :::: "volatile") };
        Port::new(HEAP_TRACE_PORT)
            .write(0xDEBC_u16)
            .write((layout.size() as u32) ^ HEAP_TRACE_KEY)
            .write((new_size as u32) ^ HEAP_TRACE_KEY);
        unsafe { asm!("cpsie i" :::: "volatile") };
    }
    if is_port_enabled(HEAP_TRACE_PORT) {
        instrument(layout, new_size);
    }
}

/// Logs shrinking in place to the ITM port #31.
///
/// This function is a no-op if no debug probe is connected and listening.
#[inline(always)]
pub fn trace_shrink_in_place(layout: Layout, new_size: usize) {
    #[inline(never)]
    fn instrument(layout: Layout, new_size: usize) {
        #[cfg(feature = "std")]
        return unimplemented!();
        unsafe { asm!("cpsid i" :::: "volatile") };
        Port::new(HEAP_TRACE_PORT)
            .write(0xCBED_u16)
            .write((layout.size() as u32) ^ HEAP_TRACE_KEY)
            .write((new_size as u32) ^ HEAP_TRACE_KEY);
        unsafe { asm!("cpsie i" :::: "volatile") };
    }
    if is_port_enabled(HEAP_TRACE_PORT) {
        instrument(layout, new_size);
    }
}