/* CH224A —— 底板的 USB-PD 受电芯片（`U36`，R2 方案 D16）。

   板上它只干一件事：用 `R7` 120 k 这一颗电阻**硬件**请求 20 V，
   降压 `U37` 再把 20 V 变成 12 V 母线。固件**不参与协商**，只做一件事：
   **读出当前这个充电器在 20 V 档最多能给多少电流**，换算成整板功率上限。

   ---- 为什么需要这个上限（计划 §5.9） ------------------------------------
   R2 的输入从 DC 头改成了 USB-C PD。单口上限 20 V × 5 A = 100 W（5 A 还要
   e-marker 线；普通 3 A 线只有 60 W），而整板最坏工况约 108 W。
   常态 10~25 W 怎么都够，但**最坏工况要靠固件限功率**（R1 §8.3 的降载）。
   充电器插的是哪一个，只有运行时才知道 —— 就是读这颗芯片。

   ┌─ ⛔ 一条禁令 ────────────────────────────────────────────────────────────┐
   │ **本驱动不提供写 `0x0A` 的接口，一个都不提供。**                          │
   │ `0x0A = 5` 是「请求 28 V EPR」。板上 `D3` 是 SMBJ22A（VRWM 22 V），       │
   │ `U37` 的 EN 分压按 20 V 设计 —— 28 V 会把 TVS 打到雪崩。                  │
   │ 这跟 `sr595.h` 不提供「抬 OE#」、`pca9555.h` 不提供「把接地脚配成输出」   │
   │ 是同一条规矩：**能烧板子的动作不给接口，而不是给了再叮嘱别用。**          │
   └──────────────────────────────────────────────────────────────────────────┘

   设计上挂在 TCA9548A 的**通道 5**（`TCA9548A_CH_PD`）上。
   ⚠️ **但 2026-09-27 板 B 实测它在主干应答**（0x22/0x23，mux 全关时也在），与设计不一致、原因未查。
   `bringup.c` 的 `pd_up()` 两处都找（先主干）；弄清之后删掉一处。 */
#ifndef CH224A_H
#define CH224A_H

#include <stdbool.h>
#include <stdint.h>

#include "hal_err.h"

#ifdef __cplusplus
extern "C" {
#endif

/* ⚠️⚠️ **这个地址还没有被实物证实**（计划 §11 的待定项）：
   R2 §36.2 只写了寄存器号，没写从机地址。所以：
     · 所有接口都**收一个 addr 参数**，不写死；
     · B1 上板扫描时把通道 5 上扫到的那个地址填回这里，并同步改计划 §5.2。
   在那之前，用这个值跑出来的「扫不到」是**预期结果**，不是固件 bug。 */
#define CH224A_ADDR_DEFAULT 0x23

/* 寄存器（R2 §36.2）。 */
#define CH224A_REG_STATUS  0x09 /* 协商状态 / 当前档位 */
#define CH224A_REG_CURRENT 0x50 /* 当前档位的最大电流，**单位 50 mA** */

/* 板上硬件固定请求的档位。`R7` 120 k 一颗电阻定死，固件改不了也不该改。 */
#define CH224A_FIXED_MV 20000

/* 0x50 那个字节 → mA。 */
uint32_t ch224a_ma_from_reg(uint8_t reg);

/* mA → 整板可用功率（mW），按 20 V 档算。
   60 W / 65 W / 100 W 三档在这里分别是 3000 / 3250 / 5000 mA。 */
uint32_t ch224a_power_limit_mw(uint32_t ma);

/* 地址不与主干上的器件撞车。⚠️ 它挂在通道 5 上，与刀片支路的 0x40 / 0x20
   本来就不冲突，这里查的是「万一它和主干某个器件同址」——
   那种情况下选到通道 5 时主干那位会被它盖住。 */
bool ch224a_addr_ok(uint8_t addr);

/* 认件：读状态寄存器。不应答 → HAL_ERR_NAK。
   ⚠️ **不校验内容**：这颗芯片没有 ID 寄存器，状态字的每一个值都是合法的。 */
hal_err_t ch224a_probe(uint8_t addr);

hal_err_t ch224a_read_status(uint8_t addr, uint8_t *status);

/* 当前档位最大电流（mA）。读失败时 `*ma` 不动。 */
hal_err_t ch224a_read_max_ma(uint8_t addr, uint32_t *ma);

#ifdef __cplusplus
}
#endif

#endif /* CH224A_H */