/* `slot` —— 一片刀片的 I/O 门面（R2 新增）。

   R2 之后，「按一下 CH3 的电源键」在总线上是：
   **选 mux 通道 2 → 改 0x20 那片 PCA9555 的 Port0 输出锁存器**。
   路号 → 通道 → 影子下标这条链只在本文件里出现一次，别处一律调 `slot_*`。

   ---- 为什么要有这一层（而不是让 t_actuator 直接调驱动）------------------

   `pca9555_write_out0(slot, ...)` 的 `slot` 参数**只用来记影子**，驱动没法验证
   它与当前 mux 通道是不是同一路。传错的后果是影子记在了另一片上，
   下一次写会把那一片的键"顺手"改掉 —— 而五路的电压电流全部正常。
   本文件把「选通道」和「记影子」绑在同一个函数里，让这件事**不可能**传错。

   ---- 两个版本的接口 ------------------------------------------------------

   带 `_locked` 后缀的**必须**在对应那一路的 `i2cbus_xact()` 回调里调
   （通道已选好、锁已持有）；不带后缀的自己开一次 `xact`。
   `t_safety` 用前者（SW-8 要在同一圈、同一把锁里断 VBUS，计划 §5.4），
   `t_actuator` 与命令处理器用后者。
   ⚠️ 在回调里调不带后缀的版本 = 嵌套 = `HAL_ERR_STATE`（`i2cbus.h` 的警告）。 */
#ifndef SLOT_H
#define SLOT_H

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

#include "hal_err.h"
#include "pca9555.h"
#include "phonerail.h"

#ifdef __cplusplus
extern "C" {
#endif

/* 不带 `_locked` 的那些函数等 I²C 锁最多等这么久。
   比 `t_safety` 的 5 ms 长：巡检等不到就跳过一圈（20 ms 后重来），
   而执行器等不到就得重试一整个状态（`ACT_ST_CLEANUP` 那条「不放弃」）。 */
#define SLOT_LOCK_TIMEOUT_MS 20

/* ---- `PRSNT#`：纯 GPIO，不经总线（计划 §5.8） ---------------------------- */

/* 五根 `PRSNT#` 配成**上拉输入**。板上另有 R606~R610 上拉，这里再配一次内部上拉
   是为了空槽时电平确定 —— 悬空的输入脚读回来是随机的，而「随机地认为刀片在位」
   正是这条判据要防的事。 */
hal_err_t slot_prsnt_init(void);

/* 刀片在不在位。**低 = 在位**（刀片把金手指 B31 短到 A1 的 GND）。

   ⚠️ 读失败时返回**上一次成功读到的值**（初值 true = 在位）。
   理由：GPIO 读在两个目标上都只可能因为「没 config」失败，那时系统还没起来；
   而让一次读失败把五台正在跑的手机判成"拔掉了"，代价比漏判大得多。 */
bool slot_present(int rail);

/* 把 `PRSNT#` 读一遍并更新缓存。`t_safety` 每圈调一次（不碰总线，很便宜）。 */
void slot_prsnt_poll(void);

/* ---- 初始化 -------------------------------------------------------------- */

/* 该路 PCA9555 的初始化（自带 `xact`）。顺序是驱动里那个框保证的：
   **输出锁存器先清零，方向最后改**。
   ⚠️ 必须在 `rail_en_init()` 之后：这一步之后 VBUS 才真的受控。 */
hal_err_t slot_init(int rail);

/* ---- VBUS（PCA9555 P0.4 → TPS22918） ------------------------------------- */

hal_err_t slot_vbus_enable(int rail, bool on);
hal_err_t slot_vbus_enable_locked(int rail, bool on);

/* 最后一次**成功**写进去的值（上电与 `slot_init()` 之后都是 false）。
   不去读回器件，因为这里要的本来就是「固件的意图」（`rail_cfg.h` 里同一条理由）。
   ⚠️ 写失败时不更新：关的那次失败 ⇒ 影子留在 on ⇒ 判据继续武装（还会再关一次）；
   开的那次失败 ⇒ 影子留在 off ⇒ 判据不武装。两边都倒向安全的那一侧。 */
bool slot_vbus_is_on(int rail);

/* ---- 三个侧键 + EDL（PCA9555 P0.0~P0.3） --------------------------------- */

/* 改 `mask` 指定的那几位。组合键的两位在**同一次写**里（§10.6）。
   `mask` 只许出现 `PCA9555_P0_OUT_MASK` 里的位。 */
hal_err_t slot_out0_write(int rail, uint8_t mask, uint8_t value);

/* 该路 Port0 输出锁存器的影子。 */
uint8_t slot_shadow(int rail);

/* ---- 输入（PCA9555 Port1） ----------------------------------------------- */

/* 一次事务读回两个输入端口。**只有 `_locked` 版本** —— 读输入的唯一调用者是
   `t_safety`，它本来就在 `xact` 里；别处要看状态请读巡检的快照
   （`t_actuator.h` 里「PG 为什么是别人喂进来的」那一段）。 */
hal_err_t slot_read_inputs_locked(int rail, pca9555_in_t *out);

/* ---- 路号 → mux 通道（唯一换算点） --------------------------------------- */

/* 这一路在 TCA9548A 上的通道号。查 `rail_cfg()`，**不算**。 */
int slot_mux_ch(int rail);

#ifdef __cplusplus
}
#endif

#endif /* SLOT_H */