diff options
Diffstat (limited to 'lib/libi2c.3')
| -rw-r--r-- | lib/libi2c.3 | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/lib/libi2c.3 b/lib/libi2c.3 new file mode 100644 index 0000000..c9374f5 --- /dev/null +++ b/lib/libi2c.3 @@ -0,0 +1,141 @@ +.\" 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>. + +.SH AUTHOR +Simon G. Vogl, Frodo Looijaard, Jean Delvare and others |