Table of Contents
The I2C protocol
This page provides the official documentation of the I2C protocol of MINIX 3. It describes the protocol used between the I2C device drivers and the I2C bus driver. The current version documents the protocol used in git commit 550fdfb and later. If you update this document because of changes to MINIX 3, please mention the commit ID of the change in the wiki comment.
General Overview
Drivers for individual I2C devices (example: the TPS65217C power management IC), henceforth called I2C device drivers, don't access the bus directly. Instead, they message a driver for the I2C bus itself, henceforth called an I2C bus driver. The bus driver is responsible for providing a consistent interface across different I2C controller hardware and for mediating access to the I2C bus.
The protocol is pretty simple and messages are only initiated by I2C device drivers. The I2C bus driver handles the messages and replies. There are only two message types used. The first, BUSC_I2C_RESERVE, is used by drivers to reserve a device on the bus. A reservation is required before performing read/write operations on the bus. Read/write operations are done with the BUSC_I2C_EXEC which passes a minix_i2c_ioctl_exec_t structure, a flattened version of the NetBSD I2C interface i2c_ioctl_exec_t.
I2C Messages
BUSC_I2C_RESERVE
Reserve an I2C device.
Request fields
| DEVICE | m2_i1 | int | Slave address of the I2C device being reserved. |
Reply fields
- none
Reply codes
| <16% >OK | Device reserved okay. |
| EBUSY | Already reserved by another endpoint. |
| EINVAL | Invalid slave address. |
Description
An I2C device driver sends this message to the I2C bus driver with the slave address it wishes to reserve for exclusive access. The I2C bus driver, which manages the reservations, will reserve the device if the slave address is a valid I2C slave address and it isn't reserved by another driver.
BUSC_I2C_EXEC
Perform a read/write operation on the I2C bus.
Request fields
| IO_GRANT | m2_p1 | cp_grant_id_t | read/write grant for a minix_i2c_ioctl_exec_t. |
Reply fields
- none
Reply codes
| <16% >OK | Operation executed successfully. |
| EBUSY | Device is reserved by another driver or bus busy indicator never went low before timeout expired (shouldn't happen normally, but could happen if the user adds one or more masters to the bus). |
| EINVAL | Invalid value in minix_i2c_ioctl_exec_t. |
| EIO | Hardware I2C controller reported an error. In most cases, the generic driver will log the error (level WARN) and attempt a soft reset of the I2C controller. |
| EPERM | Attempting to use a device without reserving it first. This is only for requests from drivers. Requests from VFS, which implies access by a user program through the /dev interface, can't reserve devices and can only use unreserved devices. |
Description
An I2C device driver sends this message to the I2C bus driver with a grant containing a minix_i2c_ioctl_exec_t structure. The I2C bus driver checks the validity of the data in the grant, verifies the reservation, performs the operation requested, puts the results into the structure, and replies to the I2C device driver.
