EasyMCP2221-compatible SMBus helper API. More...

#include <stddef.h>
#include <stdint.h>
#include "mcp2221.h"

Include dependency graph for mcp2221_smbus.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	mcp2221_smbus
	Caller-owned SMBus helper context. More...

Macros
#define	MCP2221_I2C_SMBUS_BLOCK_MAX 255
	Maximum payload length accepted by the SMBus block helpers. More...

Typedefs
typedef struct mcp2221_smbus	mcp2221_smbus_t
	Caller-owned SMBus helper context. More...

Functions
mcp2221_error_code_t	mcp2221_smbus_init (mcp2221_smbus_t bus, mcp2221_t existing_mcp, int device_index, uint16_t vid, uint16_t pid, const char *usbserial, uint32_t i2c_speed_hz)
	Initialize a caller-owned SMBus context. More...

void	mcp2221_smbus_close (mcp2221_smbus_t *bus)
	Close an SMBus context. More...

mcp2221_error_code_t	mcp2221_smbus_read_byte (mcp2221_smbus_t bus, uint8_t addr, uint8_t value)
	Read one byte directly from an SMBus target. More...

mcp2221_error_code_t	mcp2221_smbus_write_byte (mcp2221_smbus_t *bus, uint8_t addr, uint8_t value)
	Write one byte directly to an SMBus target. More...

mcp2221_error_code_t	mcp2221_smbus_read_byte_data (mcp2221_smbus_t bus, uint8_t addr, uint8_t reg, uint8_t value)
	Read one byte from an SMBus command/register. More...

mcp2221_error_code_t	mcp2221_smbus_write_byte_data (mcp2221_smbus_t *bus, uint8_t addr, uint8_t reg, uint8_t value)
	Write one byte to an SMBus command/register. More...

mcp2221_error_code_t	mcp2221_smbus_read_word_data (mcp2221_smbus_t bus, uint8_t addr, uint8_t reg, int16_t value)
	Read a 16-bit word from an SMBus command/register. More...

mcp2221_error_code_t	mcp2221_smbus_write_word_data (mcp2221_smbus_t *bus, uint8_t addr, uint8_t reg, int16_t value)
	Write a 16-bit word to an SMBus command/register. More...

mcp2221_error_code_t	mcp2221_smbus_process_call (mcp2221_smbus_t bus, uint8_t addr, uint8_t reg, int16_t value, int16_t response)
	Perform an SMBus process call. More...

mcp2221_error_code_t	mcp2221_smbus_read_block_data (mcp2221_smbus_t bus, uint8_t addr, uint8_t reg, uint8_t buffer, size_t *length)
	Read an SMBus length-prefixed block. More...

mcp2221_error_code_t	mcp2221_smbus_write_block_data (mcp2221_smbus_t bus, uint8_t addr, uint8_t reg, const uint8_t data, size_t length)
	Write an SMBus length-prefixed block. More...

mcp2221_error_code_t	mcp2221_smbus_block_process_call (mcp2221_smbus_t bus, uint8_t addr, uint8_t reg, const uint8_t data, size_t length, uint8_t response, size_t resp_len)
	Perform an SMBus block process call. More...

mcp2221_error_code_t	mcp2221_smbus_read_i2c_block_data (mcp2221_smbus_t bus, uint8_t addr, uint8_t reg, uint8_t buffer, size_t length)
	Read a fixed-length I2C block from an SMBus command/register. More...

mcp2221_error_code_t	mcp2221_smbus_write_i2c_block_data (mcp2221_smbus_t bus, uint8_t addr, uint8_t reg, const uint8_t data, size_t length)
	Write a fixed-length I2C block to an SMBus command/register. More...

Detailed Description

EasyMCP2221-compatible SMBus helper API.

Definition in file mcp2221_smbus.h.

Macro Definition Documentation

◆ MCP2221_I2C_SMBUS_BLOCK_MAX

#define MCP2221_I2C_SMBUS_BLOCK_MAX 255

Maximum payload length accepted by the SMBus block helpers.

Block lengths are encoded in a single byte. The value of 255 follows the EasyMCP2221 compatibility layer and is intentionally larger than the classic 32-byte SMBus block limit.

Definition at line 23 of file mcp2221_smbus.h.

Typedef Documentation

◆ mcp2221_smbus_t

typedef struct mcp2221_smbus mcp2221_smbus_t

Caller-owned SMBus helper context.

Initialize the context with mcp2221_smbus_init() and release it with mcp2221_smbus_close().

When initialized with an existing MCP2221 handle, the context borrows that handle. When mcp2221_smbus_init() opens the device itself, the context owns the acquired reference and mcp2221_smbus_close() releases it.

Function Documentation

◆ mcp2221_smbus_block_process_call()

mcp2221_error_code_t mcp2221_smbus_block_process_call	(	mcp2221_smbus_t *	bus,
		uint8_t	addr,
		uint8_t	reg,
		const uint8_t *	data,
		size_t	length,
		uint8_t *	response,
		size_t *	resp_len
	)

Perform an SMBus block process call.

Writes the command byte, a one-byte payload length, and the supplied payload without a STOP condition. It then reads a length-prefixed response using a repeated START.

Parameters

[in]	bus	Initialized SMBus context.
[in]	addr	7-bit I2C target address.
[in]	reg	SMBus command/register byte.
[in]	data	Payload bytes to send. Must not be `NULL`.
[in]	length	Payload length. May be 0 and must not exceed MCP2221_I2C_SMBUS_BLOCK_MAX.
[out]	response	Buffer receiving the response payload. Must hold at least MCP2221_I2C_SMBUS_BLOCK_MAX bytes.
[out]	resp_len	Receives the response payload length.

Returns: MCP2221_ERR_OK on success, MCP2221_ERR_INVALID if an argument or the reported response length is invalid, or another mcp2221_error_code_t value on failure.

◆ mcp2221_smbus_close()

void mcp2221_smbus_close ( mcp2221_smbus_t * bus )

Close an SMBus context.

If the context opened its MCP2221 handle during mcp2221_smbus_init(), one reference is released with mcp2221_close(). A borrowed handle is not closed. The context is cleared in either case.

Parameters

[in,out] bus SMBus context to close, or NULL.

Note: Passing NULL is allowed and has no effect.

◆ mcp2221_smbus_init()

mcp2221_error_code_t mcp2221_smbus_init	(	mcp2221_smbus_t *	bus,
		mcp2221_t *	existing_mcp,
		int	device_index,
		uint16_t	vid,
		uint16_t	pid,
		const char *	usbserial,
		uint32_t	i2c_speed_hz
	)

Initialize a caller-owned SMBus context.

If existing_mcp is non-NULL, the context borrows that handle and no device is opened. In that case the device-selection parameters and i2c_speed_hz are not applied.

If existing_mcp is NULL, the function opens an MCP2221 device using mcp2221_open_simple(). An i2c_speed_hz value of 0 selects 100 kHz; values greater than MCP2221_I2C_SPEED_MAX_HZ are invalid.

Parameters

[out]	bus	Caller-owned SMBus context to initialize. Must not be `NULL`.
[in]	existing_mcp	Existing MCP2221 handle to borrow, or `NULL` to open a device for this context.
[in]	device_index	Zero-based device index used when opening a device.
[in]	vid	USB vendor ID used when opening a device.
[in]	pid	USB product ID used when opening a device.
[in]	usbserial	USB serial number to match when opening a device, or `NULL` to ignore the serial number.
[in]	i2c_speed_hz	Requested I2C clock frequency in hertz when opening a device. Zero selects 100 kHz; values greater than MCP2221_I2C_SPEED_MAX_HZ are invalid.

Returns: MCP2221_ERR_OK on success, MCP2221_ERR_INVALID for a NULL bus or an out-of-range speed when opening a device, or another mcp2221_error_code_t value on failure.

See also: mcp2221_smbus_close()

◆ mcp2221_smbus_process_call()

mcp2221_error_code_t mcp2221_smbus_process_call	(	mcp2221_smbus_t *	bus,
		uint8_t	addr,
		uint8_t	reg,
		int16_t	value,
		int16_t *	response
	)

Perform an SMBus process call.

Writes a command byte and a little-endian 16-bit value without a STOP condition, then reads a little-endian 16-bit response using a repeated START.

Parameters

[in]	bus	Initialized SMBus context.
[in]	addr	7-bit I2C target address.
[in]	reg	SMBus command/register byte.
[in]	value	Signed 16-bit value to send.
[out]	response	Receives the signed 16-bit response.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

◆ mcp2221_smbus_read_block_data()

mcp2221_error_code_t mcp2221_smbus_read_block_data	(	mcp2221_smbus_t *	bus,
		uint8_t	addr,
		uint8_t	reg,
		uint8_t *	buffer,
		size_t *	length
	)

Read an SMBus length-prefixed block.

Reads one length byte followed by up to MCP2221_I2C_SMBUS_BLOCK_MAX payload bytes. The caller-provided buffer must be large enough for the maximum payload.

Parameters

[in]	bus	Initialized SMBus context.
[in]	addr	7-bit I2C target address.
[in]	reg	SMBus command/register byte.
[out]	buffer	Buffer receiving the payload. Must hold at least MCP2221_I2C_SMBUS_BLOCK_MAX bytes.
[out]	length	Receives the payload length reported by the target.

Returns: MCP2221_ERR_OK on success, MCP2221_ERR_INVALID if the reported length is invalid, or another mcp2221_error_code_t value on failure.

◆ mcp2221_smbus_read_byte()

mcp2221_error_code_t mcp2221_smbus_read_byte	(	mcp2221_smbus_t *	bus,
		uint8_t	addr,
		uint8_t *	value
	)

Read one byte directly from an SMBus target.

Parameters

[in]	bus	Initialized SMBus context.
[in]	addr	7-bit I2C target address.
[out]	value	Receives the byte read from the target.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

◆ mcp2221_smbus_read_byte_data()

mcp2221_error_code_t mcp2221_smbus_read_byte_data	(	mcp2221_smbus_t *	bus,
		uint8_t	addr,
		uint8_t	reg,
		uint8_t *	value
	)

Read one byte from an SMBus command/register.

Parameters

[in]	bus	Initialized SMBus context.
[in]	addr	7-bit I2C target address.
[in]	reg	SMBus command/register byte.
[out]	value	Receives the byte read from the target.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

◆ mcp2221_smbus_read_i2c_block_data()

mcp2221_error_code_t mcp2221_smbus_read_i2c_block_data	(	mcp2221_smbus_t *	bus,
		uint8_t	addr,
		uint8_t	reg,
		uint8_t *	buffer,
		size_t	length
	)

Read a fixed-length I2C block from an SMBus command/register.

Unlike mcp2221_smbus_read_block_data(), this helper does not consume a length prefix from the target.

Parameters

[in]	bus	Initialized SMBus context.
[in]	addr	7-bit I2C target address.
[in]	reg	SMBus command/register byte.
[out]	buffer	Buffer receiving the requested bytes.
[in]	length	Number of bytes requested. Must be from 1 through MCP2221_I2C_SMBUS_BLOCK_MAX.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

◆ mcp2221_smbus_read_word_data()

mcp2221_error_code_t mcp2221_smbus_read_word_data	(	mcp2221_smbus_t *	bus,
		uint8_t	addr,
		uint8_t	reg,
		int16_t *	value
	)

Read a 16-bit word from an SMBus command/register.

The two data bytes are decoded least-significant byte first to match the EasyMCP2221 SMBus compatibility behavior.

Parameters

[in]	bus	Initialized SMBus context.
[in]	addr	7-bit I2C target address.
[in]	reg	SMBus command/register byte.
[out]	value	Receives the decoded signed 16-bit value.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

◆ mcp2221_smbus_write_block_data()

mcp2221_error_code_t mcp2221_smbus_write_block_data	(	mcp2221_smbus_t *	bus,
		uint8_t	addr,
		uint8_t	reg,
		const uint8_t *	data,
		size_t	length
	)

Write an SMBus length-prefixed block.

The function writes the command byte, one length byte, and the supplied payload.

Parameters

[in]	bus	Initialized SMBus context.
[in]	addr	7-bit I2C target address.
[in]	reg	SMBus command/register byte.
[in]	data	Payload bytes to write. Must not be `NULL`.
[in]	length	Payload length. May be 0 and must not exceed MCP2221_I2C_SMBUS_BLOCK_MAX.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

◆ mcp2221_smbus_write_byte()

mcp2221_error_code_t mcp2221_smbus_write_byte	(	mcp2221_smbus_t *	bus,
		uint8_t	addr,
		uint8_t	value
	)

Write one byte directly to an SMBus target.

Parameters

[in]	bus	Initialized SMBus context.
[in]	addr	7-bit I2C target address.
[in]	value	Byte to write.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

◆ mcp2221_smbus_write_byte_data()

mcp2221_error_code_t mcp2221_smbus_write_byte_data	(	mcp2221_smbus_t *	bus,
		uint8_t	addr,
		uint8_t	reg,
		uint8_t	value
	)

Write one byte to an SMBus command/register.

Parameters

[in]	bus	Initialized SMBus context.
[in]	addr	7-bit I2C target address.
[in]	reg	SMBus command/register byte.
[in]	value	Byte to write.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

◆ mcp2221_smbus_write_i2c_block_data()

mcp2221_error_code_t mcp2221_smbus_write_i2c_block_data	(	mcp2221_smbus_t *	bus,
		uint8_t	addr,
		uint8_t	reg,
		const uint8_t *	data,
		size_t	length
	)

Write a fixed-length I2C block to an SMBus command/register.

Unlike mcp2221_smbus_write_block_data(), this helper does not add a payload length byte.

Parameters

[in]	bus	Initialized SMBus context.
[in]	addr	7-bit I2C target address.
[in]	reg	SMBus command/register byte.
[in]	data	Bytes to write. Must not be `NULL`.
[in]	length	Number of bytes to write. May be 0 and must not exceed MCP2221_I2C_SMBUS_BLOCK_MAX.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

◆ mcp2221_smbus_write_word_data()

mcp2221_error_code_t mcp2221_smbus_write_word_data	(	mcp2221_smbus_t *	bus,
		uint8_t	addr,
		uint8_t	reg,
		int16_t	value
	)

Write a 16-bit word to an SMBus command/register.

The value is encoded least-significant byte first.

Parameters

[in]	bus	Initialized SMBus context.
[in]	addr	7-bit I2C target address.
[in]	reg	SMBus command/register byte.
[in]	value	Signed 16-bit value to write.

Returns: MCP2221_ERR_OK on success, or another mcp2221_error_code_t value on failure.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ MCP2221_I2C_SMBUS_BLOCK_MAX

Typedef Documentation

◆ mcp2221_smbus_t

Function Documentation

◆ mcp2221_smbus_block_process_call()

◆ mcp2221_smbus_close()

◆ mcp2221_smbus_init()

◆ mcp2221_smbus_process_call()

◆ mcp2221_smbus_read_block_data()

◆ mcp2221_smbus_read_byte()

◆ mcp2221_smbus_read_byte_data()

◆ mcp2221_smbus_read_i2c_block_data()

◆ mcp2221_smbus_read_word_data()

◆ mcp2221_smbus_write_block_data()

◆ mcp2221_smbus_write_byte()

◆ mcp2221_smbus_write_byte_data()

◆ mcp2221_smbus_write_i2c_block_data()

◆ mcp2221_smbus_write_word_data()