I2C Bus Driver

Files
file	i2c-bus.c
	Inter-Integrated Circuit (I2C) Bus Implementation.

Data Structures
struct	i2c_bus
	I2C bus control. More...

Macros
#define	I2C_BUS_CLOCK_DEFAULT   100000
	Default I2C bus clock in Hz.
#define	I2C_BUS_NOBLOCK   (1u << 0)
	I2C bus transfer flag to indicate that the task should not block if the bus is busy on a new transfer.

Functions
int	i2c_bus_init (i2c_bus *bus)
	Initializes a bus control.
i2c_bus *	i2c_bus_alloc_and_init (size_t size)
	Allocates a bus control from the heap and initializes it.
void	i2c_bus_destroy (i2c_bus *bus)
	Destroys a bus control.
void	i2c_bus_destroy_and_free (i2c_bus *bus)
	Destroys a bus control and frees its memory.
int	i2c_bus_register (i2c_bus *bus, const char *bus_path)
	Registers a bus control.
int	i2c_bus_try_obtain (i2c_bus *bus)
	Try to obtain the bus.
void	i2c_bus_obtain (i2c_bus *bus)
	Obtains the bus.
void	i2c_bus_release (i2c_bus *bus)
	Releases the bus.
int	i2c_bus_transfer (i2c_bus *bus, i2c_msg *msgs, uint32_t msg_count)
	Transfers I2C messages.
int	i2c_bus_do_transfer (i2c_bus *bus, i2c_msg *msgs, uint32_t msg_count, uint32_t flags)
	Transfers I2C messages with optional flags.

I2C IO Control Commands
#define	I2C_BUS_OBTAIN   0x800
	Obtains the bus.
#define	I2C_BUS_RELEASE   0x801
	Releases the bus.
#define	I2C_BUS_GET_CONTROL   0x802
	Gets the bus control.
#define	I2C_BUS_SET_CLOCK   0x803
	Sets the bus clock in Hz.

Detailed Description

Macro Definition Documentation

I2C_BUS_GET_CONTROL

#define I2C_BUS_GET_CONTROL   0x802

Gets the bus control.

The argument type is a pointer to i2c_bus pointer.

I2C_BUS_OBTAIN

#define I2C_BUS_OBTAIN   0x800

Obtains the bus.

This command has no argument.

I2C_BUS_RELEASE

#define I2C_BUS_RELEASE   0x801

Releases the bus.

This command has no argument.

I2C_BUS_SET_CLOCK

#define I2C_BUS_SET_CLOCK   0x803

Sets the bus clock in Hz.

The argument type is unsigned long.

Function Documentation

i2c_bus_alloc_and_init()

i2c_bus * i2c_bus_alloc_and_init

(

size_t

size

)

Allocates a bus control from the heap and initializes it.

After a sucessful allocation and initialization the bus control must be destroyed via i2c_bus_destroy_and_free(). A registered bus control will be automatically destroyed in case the device file is unlinked. Make sure to call i2c_bus_destroy_and_free() in a custom destruction handler.

Parameters

[in]

size

The size of the bus control. This enables the addition of bus controller specific data to the base bus control. The bus control is zero initialized.

Return values

non-NULL	The new bus control.
NULL	An error occurred. The errno is set to indicate the error.

See also

i2c_bus_register()

i2c_bus_destroy()

void i2c_bus_destroy

(

i2c_bus *

bus

)

Destroys a bus control.

Parameters

[in]

bus

The bus control.

i2c_bus_destroy_and_free()

void i2c_bus_destroy_and_free

(

i2c_bus *

bus

)

Destroys a bus control and frees its memory.

Parameters

[in]

bus

The bus control.

i2c_bus_do_transfer()

int i2c_bus_do_transfer	(	i2c_bus *	bus,
		i2c_msg *	msgs,
		uint32_t	msg_count,
		uint32_t	flags
	)

Transfers I2C messages with optional flags.

The bus is obtained before the transfer and released afterwards. If the flag I2C_BUS_NOBLOCK is set and the bus is already obtained, nothing will be transfered and the function returns with an -EAGAIN.

Parameters

[in]	bus	The bus control.
[in]	msgs	The messages to transfer.
[in]	msg_count	The count of messages to transfer. It must be positive.
[in]	flags	Options for the whole transfer.

Return values

0	Successful operation.
-EAGAIN	if I2C_BUS_NOBLOCK is set and the bus is already obtained.
negative	Negative error number in case of an error.

i2c_bus_init()

int i2c_bus_init

(

i2c_bus *

bus

)

Initializes a bus control.

After a sucessful initialization the bus control must be destroyed via i2c_bus_destroy(). A registered bus control will be automatically destroyed in case the device file is unlinked. Make sure to call i2c_bus_destroy() in a custom destruction handler.

Parameters

[in]

bus

The bus control.

Return values

0	Successful operation.
-1	An error occurred. The errno is set to indicate the error.

See also

i2c_bus_register()

i2c_bus_obtain()

void i2c_bus_obtain

(

i2c_bus *

bus

)

Obtains the bus.

Parameters

[in]

bus

The bus control.

i2c_bus_register()

int i2c_bus_register	(	i2c_bus *	bus,
		const char *	bus_path
	)

Registers a bus control.

This function claims ownership of the bus control regardless if the registration is successful or not.

Parameters

[in]	bus	The bus control.
[in]	bus_path	The path to the bus device file.

Return values

0	Successful operation.
-1	An error occurred. The errno is set to indicate the error.

i2c_bus_release()

void i2c_bus_release

(

i2c_bus *

bus

)

Releases the bus.

Parameters

[in]

bus

The bus control.

i2c_bus_transfer()

int i2c_bus_transfer	(	i2c_bus *	bus,
		i2c_msg *	msgs,
		uint32_t	msg_count
	)

Transfers I2C messages.

The bus is obtained before the transfer and released afterwards. This is the same like calling i2c_bus_do_transfer with flags set to 0.

Parameters

[in]	bus	The bus control.
[in]	msgs	The messages to transfer.
[in]	msg_count	The count of messages to transfer. It must be positive.

Return values

0	Successful operation.
negative	Negative error number in case of an error.

i2c_bus_try_obtain()

int i2c_bus_try_obtain

(

i2c_bus *

bus

)

Try to obtain the bus.

Parameters

[in]

bus

The bus control.

Return values

0	Successful operation.
EBUSY	if mutex is already locked.