smbus.h File Reference

SMBus 3.1 transaction shapes over the shared I2C bus. More...

#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	SmbusNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Macros
#define	PROTOCORE_SMBUS_BLOCK_MAX   32
#define	PROTOCORE_SMBUS_WRITE   0u
#define	PROTOCORE_SMBUS_READ   1u

Functions
	PROTOCORE_NS_LAYOUT (SmbusNs, addr_byte, pec_write, pec_read, set_pec, pec_enabled, begin, quick, send_byte, receive_byte, write_byte, read_byte, write_word, read_word, write_block, read_block, process_call, block_process_call)
uint8_t	protocore_smbus_addr_byte (uint8_t *work, uint8_t addr, uint8_t rw)
	The address byte as it goes on the wire: the 7-bit address shifted .
uint8_t	protocore_smbus_pec_write (uint8_t *work, uint8_t addr, const uint8_t *payload, size_t len)
	PEC over a write transaction: the write address byte, then len .
uint8_t	protocore_smbus_pec_read (uint8_t *work, uint8_t addr, const uint8_t *sent, size_t slen, const uint8_t *got, size_t glen)
	PEC over a read transaction, which covers both halves and the .
void	protocore_smbus_set_pec (uint8_t *work, proto_bool on)
	Turn the Packet Error Code on or off for every transaction that .
proto_bool	protocore_smbus_pec_enabled (uint8_t *work)
	Whether the Packet Error Code is on.
proto_bool	protocore_smbus_begin (uint8_t *work)
	Bring up the shared I2C bus for SMBus traffic.
proto_bool	protocore_smbus_quick (uint8_t *work, uint8_t addr, uint8_t rw)
	Quick command: address the part with rw and stop. The direction bit .
proto_bool	protocore_smbus_send_byte (uint8_t *work, uint8_t addr, uint8_t value)
	Send byte: one byte with no command code in front of it.
proto_bool	protocore_smbus_receive_byte (uint8_t *work, uint8_t addr, uint8_t *out)
	Receive byte: one byte with no command code, from whatever the part .
proto_bool	protocore_smbus_write_byte (uint8_t *work, uint8_t addr, uint8_t cmd, uint8_t value)
	Write byte: cmd then one data byte.
proto_bool	protocore_smbus_read_byte (uint8_t *work, uint8_t addr, uint8_t cmd, uint8_t *out)
	Read byte: cmd, a repeated start, then one data byte back.
proto_bool	protocore_smbus_write_word (uint8_t *work, uint8_t addr, uint8_t cmd, uint16_t value)
	Write word: cmd then two data bytes, low byte first.
proto_bool	protocore_smbus_read_word (uint8_t *work, uint8_t addr, uint8_t cmd, uint16_t *out)
	Read word: cmd, a repeated start, then two data bytes back, low .
proto_bool	protocore_smbus_write_block (uint8_t *work, uint8_t addr, uint8_t cmd, const uint8_t *buf, size_t len)
	Block write: cmd, a count byte, then len payload bytes (at most .
proto_bool	protocore_smbus_read_block (uint8_t *work, uint8_t addr, uint8_t cmd, uint8_t *out, size_t cap, size_t *len)
	Block read: cmd, a repeated start, then a count byte and that many .
proto_bool	protocore_smbus_process_call (uint8_t *work, uint8_t addr, uint8_t cmd, uint16_t value, uint16_t *out)
	Process call: write a word to cmd and read a word back in the same .
proto_bool	protocore_smbus_block_process_call (uint8_t *work, uint8_t addr, uint8_t cmd, const uint8_t *buf, size_t len, uint8_t *out, size_t cap, size_t *out_len)
	Block process call: write len bytes to cmd and read a block back in .
uint8_t *	protocore_smbus_span (void)
	The PROTOCORE_SMBUS_BORROW bytes this module's state lives in.

Variables
PROTOCORE_NS SmbusNs Smbus	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

SMBus 3.1 transaction shapes over the shared I2C bus.

SMBus is I2C with the transaction shapes named and a checksum defined. A part that speaks it (a battery gauge, a fan controller, a power sequencer, a temperature sensor) answers a fixed set of forms rather than whatever register layout its datasheet invents, so one driver reaches all of them: quick command, send / receive byte, write / read byte and word, block write and read, and the two process calls.

The Packet Error Code is a CRC-8 over every byte of the transaction, the address bytes and their R/W bits included. It is the catalogue's CRC-8/SMBUS, so it comes from the shared engine (PROTOCORE_CRC8_SMBUS in shared/crc/crc.h) rather than a loop written here. Turn it on with protocore_smbus_set_pec; a part that does not implement PEC NACKs the extra byte.

The PEC computation is pure and host-tested. The transfers are I2C, so a build with no bus seam refuses them.

work is PROTOCORE_SMBUS_BORROW bytes the CALLER took, at an address it knows. It is not held past the call, so nothing here aliases it. How those bytes are carved is this module's and is never named here.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file smbus.h.

Macro Definition Documentation

PROTOCORE_SMBUS_BLOCK_MAX

#define PROTOCORE_SMBUS_BLOCK_MAX   32

Definition at line 36 of file smbus.h.

PROTOCORE_SMBUS_WRITE

#define PROTOCORE_SMBUS_WRITE   0u

Definition at line 38 of file smbus.h.

PROTOCORE_SMBUS_READ

#define PROTOCORE_SMBUS_READ   1u

Definition at line 40 of file smbus.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	SmbusNs	,
		addr_byte	,
		pec_write	,
		pec_read	,
		set_pec	,
		pec_enabled	,
		begin	,
		quick	,
		send_byte	,
		receive_byte	,
		write_byte	,
		read_byte	,
		write_word	,
		read_word	,
		write_block	,
		read_block	,
		process_call	,
		block_process_call
	)

protocore_smbus_addr_byte()

uint8_t protocore_smbus_addr_byte	(	uint8_t *	work,
		uint8_t	addr,
		uint8_t	rw
	)

The address byte as it goes on the wire: the 7-bit address shifted .

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	Addr
rw	Rw

Returns

The uint8_t.

protocore_smbus_pec_write()

uint8_t protocore_smbus_pec_write	(	uint8_t *	work,
		uint8_t	addr,
		const uint8_t *	payload,
		size_t	len
	)

PEC over a write transaction: the write address byte, then len .

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	7-bit device address
payload	everything after the address byte (command, then data)
len	Len

Returns

The uint8_t.

protocore_smbus_pec_read()

uint8_t protocore_smbus_pec_read	(	uint8_t *	work,
		uint8_t	addr,
		const uint8_t *	sent,
		size_t	slen,
		const uint8_t *	got,
		size_t	glen
	)

PEC over a read transaction, which covers both halves and the .

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	Addr
sent	Sent
slen	Slen
got	Got
glen	Glen

Returns

The uint8_t.

protocore_smbus_set_pec()

void protocore_smbus_set_pec	(	uint8_t *	work,
		proto_bool	on
	)

Turn the Packet Error Code on or off for every transaction that .

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
on	On

protocore_smbus_pec_enabled()

proto_bool protocore_smbus_pec_enabled

(

uint8_t *

work

)

Whether the Packet Error Code is on.

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.

Returns

PROTO_TRUE on success.

protocore_smbus_begin()

proto_bool protocore_smbus_begin

(

uint8_t *

work

)

Bring up the shared I2C bus for SMBus traffic.

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.

Returns

PROTO_TRUE on success.

protocore_smbus_quick()

proto_bool protocore_smbus_quick	(	uint8_t *	work,
		uint8_t	addr,
		uint8_t	rw
	)

Quick command: address the part with rw and stop. The direction bit .

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	Addr
rw	Rw

Returns

PROTO_TRUE on success.

protocore_smbus_send_byte()

proto_bool protocore_smbus_send_byte	(	uint8_t *	work,
		uint8_t	addr,
		uint8_t	value
	)

Send byte: one byte with no command code in front of it.

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	Addr
value	Value

Returns

PROTO_TRUE on success.

protocore_smbus_receive_byte()

proto_bool protocore_smbus_receive_byte	(	uint8_t *	work,
		uint8_t	addr,
		uint8_t *	out
	)

Receive byte: one byte with no command code, from whatever the part .

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	Addr
out	Out

Returns

PROTO_TRUE on success.

protocore_smbus_write_byte()

proto_bool protocore_smbus_write_byte	(	uint8_t *	work,
		uint8_t	addr,
		uint8_t	cmd,
		uint8_t	value
	)

Write byte: cmd then one data byte.

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	Addr
cmd	Cmd
value	Value

Returns

PROTO_TRUE on success.

protocore_smbus_read_byte()

proto_bool protocore_smbus_read_byte	(	uint8_t *	work,
		uint8_t	addr,
		uint8_t	cmd,
		uint8_t *	out
	)

Read byte: cmd, a repeated start, then one data byte back.

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	Addr
cmd	Cmd
out	Out

Returns

PROTO_TRUE on success.

protocore_smbus_write_word()

proto_bool protocore_smbus_write_word	(	uint8_t *	work,
		uint8_t	addr,
		uint8_t	cmd,
		uint16_t	value
	)

Write word: cmd then two data bytes, low byte first.

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	Addr
cmd	Cmd
value	Value

Returns

PROTO_TRUE on success.

protocore_smbus_read_word()

proto_bool protocore_smbus_read_word	(	uint8_t *	work,
		uint8_t	addr,
		uint8_t	cmd,
		uint16_t *	out
	)

Read word: cmd, a repeated start, then two data bytes back, low .

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	Addr
cmd	Cmd
out	Out

Returns

PROTO_TRUE on success.

protocore_smbus_write_block()

proto_bool protocore_smbus_write_block	(	uint8_t *	work,
		uint8_t	addr,
		uint8_t	cmd,
		const uint8_t *	buf,
		size_t	len
	)

Block write: cmd, a count byte, then len payload bytes (at most .

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	Addr
cmd	Cmd
buf	Buf
len	Len

Returns

PROTO_TRUE on success.

protocore_smbus_read_block()

proto_bool protocore_smbus_read_block	(	uint8_t *	work,
		uint8_t	addr,
		uint8_t	cmd,
		uint8_t *	out,
		size_t	cap,
		size_t *	len
	)

Block read: cmd, a repeated start, then a count byte and that many .

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	Addr
cmd	Cmd
out	caller-owned, cap bytes
cap	Cap
len	out: how many bytes the part returned

Returns

PROTO_TRUE on success.

protocore_smbus_process_call()

proto_bool protocore_smbus_process_call	(	uint8_t *	work,
		uint8_t	addr,
		uint8_t	cmd,
		uint16_t	value,
		uint16_t *	out
	)

Process call: write a word to cmd and read a word back in the same .

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	Addr
cmd	Cmd
value	Value
out	Out

Returns

PROTO_TRUE on success.

protocore_smbus_block_process_call()

proto_bool protocore_smbus_block_process_call	(	uint8_t *	work,
		uint8_t	addr,
		uint8_t	cmd,
		const uint8_t *	buf,
		size_t	len,
		uint8_t *	out,
		size_t	cap,
		size_t *	out_len
	)

Block process call: write len bytes to cmd and read a block back in .

Parameters

work	PROTOCORE_SMBUS_BORROW bytes the caller took. Not held past the call.
addr	Addr
cmd	Cmd
buf	Buf
len	Len
out	Out
cap	Cap
out_len	Out len

Returns

PROTO_TRUE on success.

protocore_smbus_span()

uint8_t * protocore_smbus_span

(

void

)

The PROTOCORE_SMBUS_BORROW bytes this module's state lives in.

Stated beside the namespace rather than on it: an entry takes a borrow, and this is where that borrow comes from. Taken once from the end of the pool, which no mark and no release walks, so the state lasts the life of the program.

Returns

the span.

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS SmbusNs Smbus PROTOCORE_UNUSED

Initial value:

= {.addr_byte = protocore_smbus_addr_byte,
                                               .pec_write = protocore_smbus_pec_write,
                                               .pec_read = protocore_smbus_pec_read,
                                               .set_pec = protocore_smbus_set_pec,
                                               .pec_enabled = protocore_smbus_pec_enabled,
                                               .begin = protocore_smbus_begin,
                                               .quick = protocore_smbus_quick,
                                               .send_byte = protocore_smbus_send_byte,
                                               .receive_byte = protocore_smbus_receive_byte,
                                               .write_byte = protocore_smbus_write_byte,
                                               .read_byte = protocore_smbus_read_byte,
                                               .write_word = protocore_smbus_write_word,
                                               .read_word = protocore_smbus_read_word,
                                               .write_block = protocore_smbus_write_block,
                                               .read_block = protocore_smbus_read_block,
                                               .process_call = protocore_smbus_process_call,
                                               .block_process_call = protocore_smbus_block_process_call}

Module namespace.

Definition at line 232 of file smbus.h.