Why isn't the new I2C API deemed as thread safe? (IDFGH-14050)

[wuyuanyi135]

Answers checklist.

• I have read the documentation ESP-IDF Programming Guide and the issue is not addressed there.
• I have updated my IDF branch (master or release) to the latest version and checked that the issue is present there.
• I have searched the issue tracker for a similar issue and not found a similar issue.

General issue report

According to the doc, only bus creation was deemed as thread safe. Tracing the source code I found that the API are all semaphore-guarded that prevent racing access on the same bus:

For example:

esp-idf/components/esp_driver_i2c/i2c_master.c

Line 898 in ce60853

if (xSemaphoreTake(i2c_dev->master_bus->bus_lock_mux, ticks_to_wait) != pdTRUE) {

If so, why are we recommended to put extra locks as per the doc?

[mythbuster5]

Yes, the doc is wrong and it will be updated soon

The factory function :cpp:func:`i2c_new_master_bus` and :cpp:func:`i2c_new_slave_device` are guaranteed to be thread safe by the driver, which means that the functions can be called from different RTOS tasks without protection by extra locks.

I2C master operation functions are also guaranteed to be thread safe by bus operation semaphore.

- :cpp:func:`i2c_master_transmit`
- :cpp:func:`i2c_master_multi_buffer_transmit`
- :cpp:func:`i2c_master_transmit_receive`
- :cpp:func:`i2c_master_receive`
- :cpp:func:`i2c_master_probe`

[wuyuanyi135]

@mythbuster5 Thank you for the confirmation