[PATCH 1/2] libi2c: Add a manual page to document the API

[Jean Delvare <jdelvare@suse.de>]

It is good practice for a library to come with a complete API description.

Signed-off-by: Jean Delvare <jdelvare@suse.de>
---
 lib/libi2c.3 |  137 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 137 insertions(+)

--- /dev/null	1970-01-01 00:00:00.000000000 +0000
+++ i2c-tools/lib/libi2c.3	2020-01-23 10:45:45.648471093 +0100
@@ -0,0 +1,137 @@
+.\" Copyright (C) 2019  Jean Delvare <jdelvare@suse.de>
+.\" libi2c is distributed under the LGPL
+.TH libi2c 3  "December 2019" "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 AUTHOR
+Simon G. Vogl, Frodo Looijaard, Jean Delvare and others

-- 
Jean Delvare
SUSE L3 Support