Device I/O

A bus-agnostic interface for transferring data to and from addressable devices - register reads/writes and raw transfers - without the caller needing to know whether the underlying bus is I2C, SPI, or (in future) something like an FTDI adapter. More...

Collaboration diagram for Device I/O:

Modules
	I2C
	Inter-Integrated Circuit (I2C) interface for hardware platforms.
	SPI
	Serial Peripheral Interface (SPI) interface for hardware platforms.

Macros
#define	HW_DEVICEIO_CAPACITY   8
	Maximum number of open device I/O handles, across every backend (SPI, I2C, ...) combined.
#define	HW_DEVICEIO_CONTEXT_SIZE   32
	Size in bytes of the per-handle scratch context space embedded in every hw_deviceio_t, for a backend's own private per-device state.

Typedefs
typedef struct hw_deviceio_t	hw_deviceio_t
	Opaque device I/O handle.

Enumerations
enum	hw_deviceio_bus_t { hw_deviceio_i2c, hw_deviceio_spi }
	Which bus backs a device I/O handle.

Lifecycle
void	hw_deviceio_deinit (hw_deviceio_t *device)
	Release a device I/O handle. More...

Properties
hw_deviceio_bus_t	hw_deviceio_bus (const hw_deviceio_t *device)
	Get which bus backs a device I/O handle. More...

Methods
size_t	hw_deviceio_xfr (hw_deviceio_t *device, void *data, size_t tx, size_t rx, uint32_t timeout_ms)
	Perform a raw, bidirectional transfer. More...
size_t	hw_deviceio_read_reg (hw_deviceio_t *device, uint8_t reg, void *data, size_t len, uint32_t timeout_ms)
	Read bytes from a register on a device. More...
size_t	hw_deviceio_write_reg (hw_deviceio_t *device, uint8_t reg, const void *data, size_t len, uint32_t timeout_ms)
	Write bytes to a register on a device. More...

Detailed Description

A bus-agnostic interface for transferring data to and from addressable devices - register reads/writes and raw transfers - without the caller needing to know whether the underlying bus is I2C, SPI, or (in future) something like an FTDI adapter.

hw_deviceio_t is the one handle type every backend hands back - hw_spi_init*() (see spi.h) and hw_i2c_init*() construct and fully own one directly, rather than wrapping some separate hw_spi_t/hw_i2c_t - so a device driver written against hw_deviceio_t works unchanged regardless of which bus actually carries it.

Function Documentation

hw_deviceio_bus()

hw_deviceio_bus_t hw_deviceio_bus

(

const hw_deviceio_t *

device

)

Get which bus backs a device I/O handle.

Parameters

device

Device handle.

Returns

The bus device was constructed against, or hw_deviceio_i2c if device is invalid.

hw_deviceio_deinit()

void hw_deviceio_deinit

(

hw_deviceio_t *

device

)

Release a device I/O handle.

Parameters

device

Device handle.

Fully releases whatever backend resources device holds (e.g. an SPI adapter's claimed pins, an I2C bus's peripheral) as well as the handle itself - there is no separate bus-specific deinit to call afterward. Safe to call on NULL.

hw_deviceio_read_reg()

size_t hw_deviceio_read_reg	(	hw_deviceio_t *	device,
		uint8_t	reg,
		void *	data,
		size_t	len,
		uint32_t	timeout_ms
	)

Read bytes from a register on a device.

Parameters

device	Device handle.
reg	Register address to read from.
data	Buffer to receive the bytes.
len	Number of bytes to read.
timeout_ms	Timeout in milliseconds for the operation. Set to 0 to use the backend's default transfer path.

Returns

Number of bytes read, or 0 on failure.

hw_deviceio_write_reg()

size_t hw_deviceio_write_reg	(	hw_deviceio_t *	device,
		uint8_t	reg,
		const void *	data,
		size_t	len,
		uint32_t	timeout_ms
	)

Write bytes to a register on a device.

Parameters

device	Device handle.
reg	Register address to write to.
data	Buffer containing bytes to write.
len	Number of bytes to write.
timeout_ms	Timeout in milliseconds for the operation. Set to 0 to use the backend's default transfer path.

Returns

Number of bytes written, or 0 on failure.

hw_deviceio_xfr()

size_t hw_deviceio_xfr	(	hw_deviceio_t *	device,
		void *	data,
		size_t	tx,
		size_t	rx,
		uint32_t	timeout_ms
	)

Perform a raw, bidirectional transfer.

Parameters

device	Device handle.
data	Buffer used for transmitted and received bytes.
tx	Number of bytes to transmit from data.
rx	Number of bytes to receive into data + tx.
timeout_ms	Timeout in milliseconds for the operation. Set to 0 to use the backend's default transfer path.

Returns

Number of bytes transferred, or 0 on failure.

Supports write-only (tx > 0, rx == 0), read-only (tx == 0, rx > 0), and write-then-read (tx > 0, rx > 0) transfers. The exact semantics of a write-then-read - a repeated start on I2C, a continuous chip-select assertion on SPI - are defined by whichever bus device is actually bound to.