A2：HAL 接口（i2c/gpio/pwm/time）+ sim 与 ESP 两套实现

接口在 components/phonerail_hal/include/，宿主机链 sim/、ESP32-S3 链 esp/
（IDF v5.4 新版 i2c_master / gpio / LEDC / esp_timer）。

sim 提供 A3 起要用的假板子控制面：假 I²C 器件（寄存器表 + 大端 + 指针自增）、
可注入 NAK / 器件失联、GPIO 外部驱动与写计数、虚拟时钟。

组件名不叫 hal —— ESP-IDF 自己有 components/hal（driver 依赖它），同名会盖掉。

验收：bash host/test.sh → 3 条 ctest 全过；build_idf.ps1 → 编过且零警告。

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01QYuExfgyYa6DzRRcUso8M8

firmware/components/phonerail_hal/include/hal_err.h

@@ -0,0 +1,25 @@
+/* HAL 的统一错误码。四路 HAL（i2c/gpio/pwm/time）共用这一套。 */
+#ifndef HAL_ERR_H
+#define HAL_ERR_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum {
+    HAL_OK = 0,
+    HAL_ERR_ARG,     /* 参数不对：引脚越界、没配就用、长度不是寄存器宽度的整数倍 */
+    HAL_ERR_NAK,     /* 器件不应答：地址错、器件失联、总线上根本没这个东西 */
+    HAL_ERR_TIMEOUT, /* 事务超时（时钟被拉死、从机时钟延展过长） */
+    HAL_ERR_BUS,     /* 仲裁丢失等其它总线级故障 */
+    HAL_ERR_STATE,   /* 没 init 就调 */
+} hal_err_t;
+
+/* 只用于日志与测试失败信息。返回的是静态字符串，不会是 NULL。 */
+const char *hal_err_str(hal_err_t err);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* HAL_ERR_H */