You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
142 lines
5.2 KiB
142 lines
5.2 KiB
.\" Copyright (C) 2019-2020 Jean Delvare <jdelvare@suse.de>
|
|
.\" libi2c is distributed under the LGPL
|
|
.TH libi2c 3 "September 2020" "i2c-tools" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
|
libi2c \- publicly accessible functions provided by the i2c library
|
|
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <linux/i2c.h>
|
|
.B #include <i2c/smbus.h>
|
|
|
|
/* Universal SMBus transaction */
|
|
.BI "__s32 i2c_smbus_access(int " file ", char " read_write ", __u8 " command ","
|
|
.BI " int " size ", union i2c_smbus_data *" data ");"
|
|
|
|
/* Simple SMBus transactions */
|
|
.BI "__s32 i2c_smbus_write_quick(int " file ", __u8 " value ");"
|
|
.BI "__s32 i2c_smbus_read_byte(int " file ");"
|
|
.BI "__s32 i2c_smbus_write_byte(int " file ", __u8 " value ");"
|
|
.BI "__s32 i2c_smbus_read_byte_data(int " file ", __u8 " command ");"
|
|
.BI "__s32 i2c_smbus_write_byte_data(int " file ", __u8 " command ", __u8 " value ");"
|
|
.BI "__s32 i2c_smbus_read_word_data(int " file ", __u8 " command ");"
|
|
.BI "__s32 i2c_smbus_write_word_data(int " file ", __u8 " command ", __u16 " value ");"
|
|
.BI "__s32 i2c_smbus_process_call(int " file ", __u8 " command ", __u16 " value ");"
|
|
|
|
/* Block SMBus (and non-SMBus) transactions */
|
|
.BI "__s32 i2c_smbus_read_block_data(int " file ", __u8 " command ", __u8 *" values ");"
|
|
.BI "__s32 i2c_smbus_write_block_data(int " file ", __u8 " command ", __u8 " length ","
|
|
.BI " const __u8 *" values ");"
|
|
.BI "__s32 i2c_smbus_block_process_call(int " file ", __u8 " command ", __u8 " length ","
|
|
.BI " __u8 *" values ");"
|
|
.BI "__s32 i2c_smbus_read_i2c_block_data(int " file ", __u8 " command ", __u8 " length ","
|
|
.BI " __u8 *" values ");"
|
|
.BI "__s32 i2c_smbus_write_i2c_block_data(int " file ", __u8 " command ", __u8 " length ","
|
|
.BI " const __u8 *" values ");"
|
|
|
|
.SH DESCRIPTION
|
|
This library offers to user-space an SMBus-level API similar to the in-kernel
|
|
one.
|
|
Each function is a wrapper around the appropriate ioctl call for i2c-dev to
|
|
process.
|
|
The i2c-dev kernel driver will convert the ioctl to its in-kernel
|
|
equivalent function call, and pass the result back to the user-space caller.
|
|
|
|
.B i2c_smbus_access()
|
|
is the universal function to run any SMBus transaction.
|
|
You have to fill out and link the data structures yourself.
|
|
It returns 0 on success, or a negative \fBerrno\fR value on error.
|
|
In practice you should never need to call this function directly, instead use
|
|
one of the specific functions below, which will prepare the data and then
|
|
call it for you.
|
|
|
|
.B i2c_smbus_write_quick()
|
|
runs an SMBus "Quick command" transaction.
|
|
|
|
.B i2c_smbus_write_byte()
|
|
runs an SMBus "Send byte" transaction.
|
|
|
|
.B i2c_smbus_write_byte_data()
|
|
runs an SMBus "Write byte" transaction.
|
|
|
|
.B i2c_smbus_write_word_data()
|
|
runs an SMBus "Write word" transaction.
|
|
|
|
These write transaction functions return 0 on success.
|
|
On error, a negative \fBerrno\fR value is returned.
|
|
|
|
.B i2c_smbus_read_byte()
|
|
runs an SMBus "Receive byte" transaction.
|
|
|
|
.B i2c_smbus_read_byte_data()
|
|
runs an SMBus "Read byte" transaction.
|
|
|
|
.B i2c_smbus_read_word_data()
|
|
runs an SMBus "Read word" transaction.
|
|
|
|
.B i2c_smbus_process_call()
|
|
runs an SMBus "Process call" transaction.
|
|
|
|
These read transaction functions return the read byte or word value on success.
|
|
On error, a negative \fBerrno\fR value is returned.
|
|
|
|
.B i2c_smbus_write_block_data()
|
|
runs an SMBus "Block write" transaction.
|
|
|
|
.B i2c_smbus_read_block_data()
|
|
runs an SMBus "Block read" transaction.
|
|
|
|
.B i2c_smbus_block_process_call()
|
|
runs an SMBus "Block write-block read process call" transaction.
|
|
|
|
These block transaction functions return 0 on success.
|
|
On error, a negative \fBerrno\fR value is returned.
|
|
The block length is limited to 32 bytes.
|
|
|
|
.B i2c_smbus_write_i2c_block_data()
|
|
runs an "I2C block write" transaction. This is typically used to write to
|
|
an EEPROM up to 4 kb in size.
|
|
|
|
.B i2c_smbus_read_i2c_block_data()
|
|
runs an "I2C block read" transaction. This is typically used to read from
|
|
an EEPROM up to 4 kb in size.
|
|
|
|
While technically not part of the SMBus specification, these I2C block
|
|
transactions are supported by many SMBus host controllers.
|
|
These block transaction functions return 0 on success.
|
|
On error, a negative \fBerrno\fR value is returned.
|
|
Like their SMBus counterparts, the block length is limited to 32 bytes.
|
|
|
|
.SH DATA STRUCTURES
|
|
|
|
Structure \fBi2c_smbus_ioctl_data\fR is used to send data to and retrieve
|
|
data from the kernel through the i2c-dev driver.
|
|
It will be filled out for you by \fBi2c_smbus_access()\fR so you do not need
|
|
to care about the details.
|
|
|
|
Union \fBi2c_smbus_data\fR is used to store all possible SMBus data.
|
|
|
|
union \fBi2c_smbus_data\fR {
|
|
.br
|
|
\fB__u8\fR byte;
|
|
.br
|
|
\fB__u16\fR word;
|
|
.br
|
|
\fB__u8\fR block[I2C_SMBUS_BLOCK_MAX + 2];
|
|
.br
|
|
};
|
|
|
|
\fBblock[0]\fR is used for length and the last byte is reserved.
|
|
If you use the higher-level functions, this structure will be filled out for
|
|
you so you do not have to care about the details.
|
|
Only if you call \fBi2c_smbus_access()\fR directly, you need to fill it out
|
|
yourself.
|
|
|
|
.SH BUGS
|
|
To report bugs or send fixes, please write to the Linux I2C mailing list
|
|
<linux-i2c@vger.kernel.org> with Cc to the current maintainer:
|
|
Jean Delvare <jdelvare@suse.de>.
|
|
|
|
.SH AUTHOR
|
|
Simon G. Vogl, Frodo Looijaard, Jean Delvare and others
|