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

DEVICEm2_i1intSlave address of the I2C device being reserved.

Reply fields

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_GRANTm2_p1cp_grant_id_tread/write grant for a minix_i2c_ioctl_exec_t.

Reply fields

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.
EPERMAttempting 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.