第 14 章：性能与体积优化

# Cargo.toml

[profile.release]
# === 优化级别 ===
opt-level = "z"       # "z" = 极致体积优化（类比 -Oz）
                      # "s" = 体积优化（类比 -Os）
                      # 3   = 速度优化（类比 -O3）
                      # 2   = 默认（类比 -O2）

# === 链接时优化 ===
lto = true            # 启用 LTO（类比 -flto）
                      # true = "fat" LTO（最彻底，编译最慢）
                      # "thin" = 薄 LTO（折中方案）
                      # false = 不启用

# === 代码生成单元 ===
codegen-units = 1     # 单单元（类比 -fno-toplevel-reorder）
                      # 默认 16，减小到 1 可以让 LLVM 做更多跨模块优化
                      # 代价：编译时间增加

# === Panic 策略 ===
panic = "abort"       # 移除 unwind 代码（类比 -fno-exceptions）
                      # 嵌入式中几乎总是用这个

# === 符号信息 ===
strip = true          # 移除符号表（类比 -s）
                      # 减小最终二进制体积

# === 调试信息 ===
debug = 0             # 不生成调试信息（类比 -g0）
                      # 开发时可设为 1 或 2

# === 增量编译 ===
incremental = false   # 关闭增量编译（Release 中通常关闭）

// 你写的代码
async fn blink(mut led: Output<'static>) {
    loop {
        led.toggle();
        Timer::after_millis(500).await;
    }
}

// 编译器生成的等价代码（简化）
enum BlinkFuture {
    State0 { led: Output<'static> },
    State1 { led: Output<'static>, timer: TimerFuture },
}

impl Future for BlinkFuture {
    type Output = ();
    
    fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<()> {
        loop {
            match self.state {
                State0 { led } => {
                    led.toggle();           // 直接执行
                    let timer = Timer::after_millis(500);
                    self.state = State1 { led, timer };
                    // 继续循环，立即 poll timer
                }
                State1 { led, timer } => {
                    match timer.poll(cx) {
                        Poll::Ready(()) => {
                            self.state = State0 { led };
                            // 继续循环，回到 State0
                        }
                        Poll::Pending => {
                            return Poll::Pending;  // 让出 CPU
                        }
                    }
                }
            }
        }
    }
}

// 方案 A：Embassy 异步
#[embassy_executor::task]
async fn read_sensor(mut i2c: I2c<'static>) {
    loop {
        let data = i2c.read(0x76, &mut buf).await;  // DMA 传输，CPU 空闲
        process(data);
        Timer::after_millis(100).await;
    }
}

// 方案 B：C 风格轮询（等价实现）
// while (1) {
//     HAL_I2C_Master_Transmit(&hi2c1, 0x76, cmd, 1, 100);  // 阻塞等待
//     HAL_I2C_Master_Receive(&hi2c1, 0x76, buf, 2, 100);   // 阻塞等待
//     process(buf);
//     HAL_Delay(100);  // 阻塞等待
// }

// 不好：在任务中处理时间关键逻辑
#[embassy_executor::task]
async fn motor_control(pwm: Pwm<'static>) {
    loop {
        let error = read_encoder().await;
        let output = pid_compute(error);
        pwm.set_duty(output);
        Timer::after_micros(100).await;  // 10 kHz 控制环
        // 问题：Timer 的精度取决于 Executor 的 poll 频率
        // 如果其他任务占用 CPU，控制环周期会抖动
    }
}

// 好：用硬件定时器中断驱动控制环
#[interrupt]
fn TIM2() {
    // 10 kHz 硬件定时器中断，精确到微秒级
    let error = read_encoder_sync();
    let output = pid_compute(error);
    set_pwm_duty_sync(output);
    // 清除中断标志
}

use embassy_executor::InterruptExecutor;
use embassy_stm32::interrupt;

static EXECUTOR_HIGH: InterruptExecutor = InterruptExecutor::new();

#[interrupt]
unsafe fn UART4() {
    // 高优先级中断驱动的 Executor
    EXECUTOR_HIGH.on_interrupt();
}

#[embassy_executor::task]
async fn critical_task() {
    // 这个任务在 UART4 中断优先级下运行
    // 可以抢占低优先级的协作式任务
    loop {
        let data = read_critical_sensor().await;
        emergency_check(data);
    }
}

// Embassy 允许为不同外设配置不同的中断优先级
// 优先级数值越小，优先级越高（与 C 的 NVIC 一致）

// .cargo/config.toml 或代码中配置：
// 高优先级：时间关键的外设
// 低优先级：非时间关键的通信

// 在 embassy-stm32 中，优先级通过 interrupt 模块配置
use embassy_stm32::interrupt;

// 设置 UART 中断优先级为 2（较高）
interrupt::UART4.set_priority(interrupt::Priority::P2);

// 设置 Timer 中断优先级为 0（最高，用于控制环）
interrupt::TIM2.set_priority(interrupt::Priority::P0);

// 设置 I2C 中断优先级为 3（较低，传感器读取不紧急）
interrupt::I2C1_EV.set_priority(interrupt::Priority::P3);

// 错误：这个循环没有真正的 .await 点
#[embassy_executor::task]
async fn bad_task() {
    loop {
        // 做一些计算...
        let result = heavy_computation();
        
        // 这个 .await 可能立即返回 Ready（如果条件已满足）
        // 不会真正让出 CPU
        some_signal.wait().await;  // 如果 signal 已经有值，立即返回
    }
}

// 修复：确保每次循环都有真正的让出点
#[embassy_executor::task]
async fn good_task() {
    loop {
        let result = heavy_computation();
        
        // 方案 1：显式 yield
        embassy_executor::yield_now().await;
        
        // 方案 2：使用 Timer（同时控制循环频率）
        Timer::after_micros(10).await;
    }
}

// 危险：深层嵌套的 async 调用
#[embassy_executor::task]
async fn dangerous_task() {
    level1().await;
}

async fn level1() {
    let buf1 = [0u8; 512];  // 512 字节
    level2().await;          // level2 的 Future 嵌套在 level1 的 Future 中
}

async fn level2() {
    let buf2 = [0u8; 512];  // 又 512 字节
    level3().await;
}

async fn level3() {
    let buf3 = [0u8; 512];  // 又 512 字节
    // 总 Future 大小：512 + 512 + 512 + 元数据 ≈ 1.6 KB
    // 如果任务分配的空间不够，就会溢出
}

// 方案 1：将大缓冲区改为静态分配
static BUF1: StaticCell<[u8; 512]> = StaticCell::new();

async fn level1() {
    let buf = BUF1.init([0u8; 512]);  // 不占 Future 空间
    level2().await;
}

// 方案 2：使用 Box（如果启用了 alloc）
// 不推荐在嵌入式中使用

// 方案 3：减少嵌套深度，将逻辑扁平化
async fn flat_task() {
    let buf = [0u8; 512];  // 只有一份缓冲区
    // 所有操作在同一个函数中完成
    do_step1(&mut buf).await;
    do_step2(&mut buf).await;
    do_step3(&mut buf).await;
}

// 错误：在 Mutex 内 .await（可能导致死锁或长时间阻塞）
static SHARED: Mutex<CriticalSectionRawMutex, SharedState> = Mutex::new(SharedState::new());

#[embassy_executor::task]
async fn bad_task() {
    let mut state = SHARED.lock().await;
    
    // 在持有锁的情况下做 I/O（其他任务全部等待！）
    state.data = read_sensor().await;  // ← 危险：I/O 可能耗时很长
    
    // 在持有锁的情况下发送数据
    CHANNEL.send(state.data).await;    // ← 危险：Channel 满时会等待
    
    drop(state);  // 释放锁
}

// 修复：最小化锁的持有时间
#[embassy_executor::task]
async fn good_task() {
    // 先在锁外做 I/O
    let data = read_sensor().await;
    
    // 只在修改共享状态时持锁
    {
        let mut state = SHARED.lock().await;
        state.data = data;
        state.timestamp = now();
    }  // 锁在这里释放
    
    // 在锁外发送数据
    CHANNEL.send(data).await;
}

// STM32H7：D-Cache Line = 32 字节，DMA 缓冲区必须 32 字节对齐
#[repr(C, align(32))]
struct DmaBuf {
    data: [u8; 256],
}

// nRF52：EasyDMA 要求 4 字节对齐
#[repr(C, align(4))]
struct DmaBuf {
    data: [u8; 256],
}

// RP2040：无特殊对齐要求（但 4 字节对齐是好的实践）
#[repr(C, align(4))]
struct DmaBuf {
    data: [u8; 256],
}