i2c.h File Reference

The one owner of the shared I2C bus for the peripheral drivers. More...

#include "config/platform/platform.h"
#include "protocore_config.h"

Go to the source code of this file.

Macros
#define	PROTOCORE_I2C_HZ   100000u
	Bus clock for the shared peripheral bus; 100 kHz standard mode.
#define	PROTOCORE_I2C_TIMEOUT_MS   50u
	Per-transfer timeout in milliseconds.
#define	PROTOCORE_I2C_BUS   0u
	Controller the plain verbs drive.
#define	PROTOCORE_I2C_HZ_STANDARD   100000u
	Standard-mode, fast-mode and fast-mode-plus bus clocks.
#define	PROTOCORE_I2C_HZ_FAST   400000u
#define	PROTOCORE_I2C_HZ_FAST_PLUS   1000000u
#define	PROTOCORE_I2C_ADDR10(a)   ((uint16_t)(PROTOCORE_I2C_ADDR_10BIT | ((a) & PROTOCORE_I2C_ADDR_MASK)))
	Wrap a 10-bit address so a transfer verb puts the two-byte form on the wire.
#define	PROTOCORE_I2C_SCAN_FIRST   0x08u
	Lowest and highest 7-bit addresses a scan reports; 0x00 - 0x07 and 0x78 - 0x7F are reserved.
#define	PROTOCORE_I2C_SCAN_LAST   0x77u

Functions
PROTOCORE_BEGIN_DECLS PROTOCORE_INLINE proto_bool	protocore_i2c_begin_on (uint8_t bus, int sda, int scl, uint32_t hz)
PROTOCORE_INLINE proto_bool	protocore_i2c_begin (void)
PROTOCORE_INLINE proto_bool	protocore_i2c_write_on (uint8_t bus, uint16_t addr, const uint8_t *buf, size_t len)
PROTOCORE_INLINE proto_bool	protocore_i2c_write (uint16_t addr, const uint8_t *buf, size_t len)
PROTOCORE_INLINE proto_bool	protocore_i2c_read_on (uint8_t bus, uint16_t addr, uint8_t *buf, size_t len)
PROTOCORE_INLINE proto_bool	protocore_i2c_read (uint16_t addr, uint8_t *buf, size_t len)
PROTOCORE_INLINE proto_bool	protocore_i2c_write_read_on (uint8_t bus, uint16_t addr, const uint8_t *w, size_t wlen, uint8_t *r, size_t rlen)
PROTOCORE_INLINE proto_bool	protocore_i2c_write_read (uint16_t addr, const uint8_t *w, size_t wlen, uint8_t *r, size_t rlen)
PROTOCORE_INLINE proto_bool	protocore_i2c_set_clock_on (uint8_t bus, uint32_t hz)
PROTOCORE_INLINE proto_bool	protocore_i2c_set_clock (uint32_t hz)
PROTOCORE_INLINE proto_bool	protocore_i2c_probe_on (uint8_t bus, uint16_t addr)
PROTOCORE_INLINE proto_bool	protocore_i2c_probe (uint16_t addr)
PROTOCORE_INLINE size_t	protocore_i2c_scan_on (uint8_t bus, uint8_t *out, size_t cap)
PROTOCORE_INLINE size_t	protocore_i2c_scan (uint8_t *out, size_t cap)
PROTOCORE_INLINE proto_bool	protocore_i2c_general_call_on (uint8_t bus, const uint8_t *buf, size_t len)
PROTOCORE_INLINE proto_bool	protocore_i2c_general_call (const uint8_t *buf, size_t len)
PROTOCORE_INLINE proto_bool	protocore_i2c_recover_on (uint8_t bus, int sda, int scl)
PROTOCORE_INLINE proto_bool	protocore_i2c_recover (void)

Detailed Description

The one owner of the shared I2C bus for the peripheral drivers.

The sensor / peripheral drivers (RTC, SHT3x, MPR121, ADS1115, INA219, PCA9685, VL53L0X, LDC1614, FDC2214) share one bus and bring it up through these verbs. The pins come from PROTOCORE_I2C_SDA_PIN / PROTOCORE_I2C_SCL_PIN (default -1 = the platform default GPIO 21 / 22). Re-begin is idempotent, so per-driver calls are harmless.

This covers the master half of the protocol. The three transfer shapes a driver reaches for are a write, a read, and a register read, which is a write and a read joined by a repeated start. The rest of what the bus can express is here too: a bus scan, an address probe, the general call, 10-bit addressing, a per-transfer clock, and recovery of a bus a device is holding low.

Every verb has a plain form on the default bus (PROTOCORE_I2C_BUS) and an _on form naming a controller, so a board with two I2C controllers drives both through one owner.

An address is 7-bit unless it is wrapped in PROTOCORE_I2C_ADDR10, which selects the 10-bit form.

The bodies compile wherever the platform states a bus.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file i2c.h.

Macro Definition Documentation

PROTOCORE_I2C_HZ

#define PROTOCORE_I2C_HZ   100000u

Bus clock for the shared peripheral bus; 100 kHz standard mode.

Definition at line 38 of file i2c.h.

PROTOCORE_I2C_TIMEOUT_MS

#define PROTOCORE_I2C_TIMEOUT_MS   50u

Per-transfer timeout in milliseconds.

Definition at line 43 of file i2c.h.

PROTOCORE_I2C_BUS

#define PROTOCORE_I2C_BUS   0u

Controller the plain verbs drive.

Definition at line 48 of file i2c.h.

PROTOCORE_I2C_HZ_STANDARD

#define PROTOCORE_I2C_HZ_STANDARD   100000u

Standard-mode, fast-mode and fast-mode-plus bus clocks.

Definition at line 52 of file i2c.h.

PROTOCORE_I2C_HZ_FAST

#define PROTOCORE_I2C_HZ_FAST   400000u

Definition at line 53 of file i2c.h.

PROTOCORE_I2C_HZ_FAST_PLUS

#define PROTOCORE_I2C_HZ_FAST_PLUS   1000000u

Definition at line 54 of file i2c.h.

PROTOCORE_I2C_ADDR10

#define PROTOCORE_I2C_ADDR10

(

a

)

((uint16_t)(PROTOCORE_I2C_ADDR_10BIT | ((a) & PROTOCORE_I2C_ADDR_MASK)))

Wrap a 10-bit address so a transfer verb puts the two-byte form on the wire.

Definition at line 57 of file i2c.h.

PROTOCORE_I2C_SCAN_FIRST

#define PROTOCORE_I2C_SCAN_FIRST   0x08u

Lowest and highest 7-bit addresses a scan reports; 0x00 - 0x07 and 0x78 - 0x7F are reserved.

Definition at line 60 of file i2c.h.

PROTOCORE_I2C_SCAN_LAST

#define PROTOCORE_I2C_SCAN_LAST   0x77u

Definition at line 61 of file i2c.h.

Function Documentation

protocore_i2c_begin_on()

PROTOCORE_BEGIN_DECLS PROTOCORE_INLINE proto_bool protocore_i2c_begin_on	(	uint8_t	bus,
		int	sda,
		int	scl,
		uint32_t	hz
	)

Definition at line 194 of file i2c.h.

References PROTO_TRUE.

protocore_i2c_begin()

PROTOCORE_INLINE proto_bool protocore_i2c_begin

(

void

)

Definition at line 203 of file i2c.h.

References PROTO_TRUE.

protocore_i2c_write_on()

PROTOCORE_INLINE proto_bool protocore_i2c_write_on	(	uint8_t	bus,
		uint16_t	addr,
		const uint8_t *	buf,
		size_t	len
	)

Definition at line 208 of file i2c.h.

References PROTO_FALSE.

Referenced by protocore_i2c_general_call_on(), and protocore_i2c_write().

protocore_i2c_write()

PROTOCORE_INLINE proto_bool protocore_i2c_write	(	uint16_t	addr,
		const uint8_t *	buf,
		size_t	len
	)

Definition at line 217 of file i2c.h.

References PROTOCORE_I2C_BUS, and protocore_i2c_write_on().

protocore_i2c_read_on()

PROTOCORE_INLINE proto_bool protocore_i2c_read_on	(	uint8_t	bus,
		uint16_t	addr,
		uint8_t *	buf,
		size_t	len
	)

Definition at line 222 of file i2c.h.

References PROTO_FALSE.

Referenced by protocore_i2c_read().

protocore_i2c_read()

PROTOCORE_INLINE proto_bool protocore_i2c_read	(	uint16_t	addr,
		uint8_t *	buf,
		size_t	len
	)

Definition at line 231 of file i2c.h.

References PROTOCORE_I2C_BUS, and protocore_i2c_read_on().

protocore_i2c_write_read_on()

PROTOCORE_INLINE proto_bool protocore_i2c_write_read_on	(	uint8_t	bus,
		uint16_t	addr,
		const uint8_t *	w,
		size_t	wlen,
		uint8_t *	r,
		size_t	rlen
	)

Definition at line 236 of file i2c.h.

References PROTO_FALSE.

Referenced by protocore_i2c_write_read().

protocore_i2c_write_read()

PROTOCORE_INLINE proto_bool protocore_i2c_write_read	(	uint16_t	addr,
		const uint8_t *	w,
		size_t	wlen,
		uint8_t *	r,
		size_t	rlen
	)

Definition at line 248 of file i2c.h.

References PROTOCORE_I2C_BUS, and protocore_i2c_write_read_on().

protocore_i2c_set_clock_on()

PROTOCORE_INLINE proto_bool protocore_i2c_set_clock_on	(	uint8_t	bus,
		uint32_t	hz
	)

Definition at line 254 of file i2c.h.

References PROTO_TRUE.

protocore_i2c_set_clock()

PROTOCORE_INLINE proto_bool protocore_i2c_set_clock

(

uint32_t

hz

)

Definition at line 261 of file i2c.h.

References PROTO_TRUE.

protocore_i2c_probe_on()

PROTOCORE_INLINE proto_bool protocore_i2c_probe_on	(	uint8_t	bus,
		uint16_t	addr
	)

Definition at line 267 of file i2c.h.

References PROTO_FALSE.

Referenced by protocore_i2c_probe(), and protocore_i2c_scan_on().

protocore_i2c_probe()

PROTOCORE_INLINE proto_bool protocore_i2c_probe

(

uint16_t

addr

)

Definition at line 274 of file i2c.h.

References PROTOCORE_I2C_BUS, and protocore_i2c_probe_on().

protocore_i2c_scan_on()

PROTOCORE_INLINE size_t protocore_i2c_scan_on	(	uint8_t	bus,
		uint8_t *	out,
		size_t	cap
	)

Definition at line 279 of file i2c.h.

References protocore_i2c_probe_on(), PROTOCORE_I2C_SCAN_FIRST, and PROTOCORE_I2C_SCAN_LAST.

Referenced by protocore_i2c_scan().

protocore_i2c_scan()

PROTOCORE_INLINE size_t protocore_i2c_scan	(	uint8_t *	out,
		size_t	cap
	)

Definition at line 293 of file i2c.h.

References PROTOCORE_I2C_BUS, and protocore_i2c_scan_on().

protocore_i2c_general_call_on()

PROTOCORE_INLINE proto_bool protocore_i2c_general_call_on	(	uint8_t	bus,
		const uint8_t *	buf,
		size_t	len
	)

Definition at line 298 of file i2c.h.

References protocore_i2c_write_on().

Referenced by protocore_i2c_general_call().

protocore_i2c_general_call()

PROTOCORE_INLINE proto_bool protocore_i2c_general_call	(	const uint8_t *	buf,
		size_t	len
	)

Definition at line 303 of file i2c.h.

References PROTOCORE_I2C_BUS, and protocore_i2c_general_call_on().

protocore_i2c_recover_on()

PROTOCORE_INLINE proto_bool protocore_i2c_recover_on	(	uint8_t	bus,
		int	sda,
		int	scl
	)

Definition at line 308 of file i2c.h.

References PROTO_FALSE.

protocore_i2c_recover()

PROTOCORE_INLINE proto_bool protocore_i2c_recover

(

void

)

Definition at line 316 of file i2c.h.

References PROTO_FALSE.