phonerail/firmware/components/phonerail_hal/esp/hal_i2c_esp.c

/* I²C 的 ESP-IDF v5.4 实现（新版 i2c_master 驱动，不是已废弃的 driver/i2c.h）。 */
#include <string.h>

#include "driver/i2c_master.h"
#include "hal_i2c.h"
#include "hal_i2c_acct.h"

#define I2C_XFER_TIMEOUT_MS 50
#define I2C_DEFAULT_FREQ_HZ 400000

static i2c_master_bus_handle_t s_bus;
static i2c_master_dev_handle_t s_devs[128]; /* 按 7 位地址索引，用到才建 */
static uint32_t                s_freq_hz;

static hal_err_t map_err(esp_err_t e)
{
    switch (e) {
    case ESP_OK:                return HAL_OK;
    case ESP_ERR_INVALID_ARG:   return HAL_ERR_ARG;
    case ESP_ERR_INVALID_STATE: return HAL_ERR_STATE;
    case ESP_ERR_TIMEOUT:       return HAL_ERR_TIMEOUT;
    case ESP_ERR_NOT_FOUND:     return HAL_ERR_NAK;
    case ESP_FAIL:              return HAL_ERR_NAK; /* 从机没 ACK 走这条 */
    default:                    return HAL_ERR_BUS;
    }
}

/* 传输函数专用。⚠️ IDF 5.4 的 i2c_master_transmit / receive / transmit_receive 在**从机 NACK**
   （以及硬件 SCL 超时）时返回的是 ESP_ERR_INVALID_STATE，不是 ESP_FAIL（i2c_master.c
   s_i2c_synchronous_transaction：「status != DONE ⇒ INVALID_STATE」）。照 map_err 翻成
   HAL_ERR_STATE（= 没 init）的话，真板上所有「器件不应答」都长得像「没初始化」——
   2026-09-27 实测：I2C_LOST 事件的错误码是 5，`power` 关电回 `busy`。sim 回的是 NAK，宿主机测不出来。
   总线没建起来的情况在调它之前已经单独返回 HAL_ERR_STATE 了（dev_of）。 */
static hal_err_t map_xfer_err(esp_err_t e)
{
    return (e == ESP_ERR_INVALID_STATE) ? HAL_ERR_NAK : map_err(e);
}

hal_err_t hal_i2c_init(const hal_i2c_cfg_t *cfg)
{
    if (cfg == NULL || cfg->sda_gpio < 0 || cfg->scl_gpio < 0) {
        return HAL_ERR_ARG;
    }
    if (s_bus != NULL) {
        return HAL_OK; /* 幂等 */
    }
    i2c_master_bus_config_t bc = {
        .i2c_port = -1, /* 自动选口 */
        .sda_io_num = (gpio_num_t)cfg->sda_gpio,
        .scl_io_num = (gpio_num_t)cfg->scl_gpio,
        .clk_source = I2C_CLK_SRC_DEFAULT,
        .glitch_ignore_cnt = 7,
        /* 板上已有 4.7 kΩ 外部上拉（设计文档 §8.2），内部上拉 45 kΩ 太弱，
           开着只会掩盖「上拉电阻漏焊」这类问题。 */
        .flags.enable_internal_pullup = false,
    };
    esp_err_t e = i2c_new_master_bus(&bc, &s_bus);
    if (e != ESP_OK) {
        return map_err(e);
    }
    s_freq_hz = cfg->freq_hz != 0 ? cfg->freq_hz : I2C_DEFAULT_FREQ_HZ;
    hal_i2c_acct_set_freq(s_freq_hz); /* 占用核算按真实速率折算，见 hal_i2c_acct.h */
    return HAL_OK;
}

static hal_err_t dev_of(uint8_t addr, i2c_master_dev_handle_t *out)
{
    if (s_bus == NULL) {
        return HAL_ERR_STATE;
    }
    if (addr > 0x7f) {
        return HAL_ERR_ARG;
    }
    if (s_devs[addr] == NULL) {
        i2c_device_config_t dc = {
            .dev_addr_length = I2C_ADDR_BIT_LEN_7,
            .device_address = addr,
            .scl_speed_hz = s_freq_hz,
        };
        esp_err_t e = i2c_master_bus_add_device(s_bus, &dc, &s_devs[addr]);
        if (e != ESP_OK) {
            return map_err(e);
        }
    }
    *out = s_devs[addr];
    return HAL_OK;
}

hal_err_t hal_i2c_write(uint8_t addr, const uint8_t *data, size_t len)
{
    i2c_master_dev_handle_t dev;
    hal_err_t err = dev_of(addr, &dev);
    if (err != HAL_OK) {
        return err;
    }
    hal_i2c_acct_add(len, 0);
    return map_xfer_err(i2c_master_transmit(dev, data, len, I2C_XFER_TIMEOUT_MS));
}

hal_err_t hal_i2c_read(uint8_t addr, uint8_t *data, size_t len)
{
    i2c_master_dev_handle_t dev;
    hal_err_t err = dev_of(addr, &dev);
    if (err != HAL_OK) {
        return err;
    }
    hal_i2c_acct_add(0, len);
    return map_xfer_err(i2c_master_receive(dev, data, len, I2C_XFER_TIMEOUT_MS));
}

hal_err_t hal_i2c_write_read(uint8_t addr, const uint8_t *wr, size_t wr_len,
                             uint8_t *rd, size_t rd_len)
{
    i2c_master_dev_handle_t dev;
    hal_err_t err = dev_of(addr, &dev);
    if (err != HAL_OK) {
        return err;
    }
    hal_i2c_acct_add(wr_len, rd_len);
    return map_xfer_err(i2c_master_transmit_receive(dev, wr, wr_len, rd, rd_len,
                                               I2C_XFER_TIMEOUT_MS));
}

hal_err_t hal_i2c_probe(uint8_t addr)
{
    if (s_bus == NULL) {
        return HAL_ERR_STATE;
    }
    hal_i2c_acct_add(0, 0);
    return map_err(i2c_master_probe(s_bus, addr, I2C_XFER_TIMEOUT_MS));
}