zhaohe
/
git.kernel.org.pub.scm.utils.i2c-tools
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

libi2c: Add a manual page to document the API 

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

Signed-off-by: Jean Delvare <jdelvare@suse.de>
tags/v4.2
Jean Delvare 5 years ago
parent
a235aabbff
commit
cdb9eefc64
3 changed files with 146 additions and 2 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 1
      Makefile
  2. 6
      lib/Module.mk
  3. 141
      lib/libi2c.3

1
Makefile
View File

@ -12,6 +12,7 @@ PREFIX ?= /usr/local
bindir = $(PREFIX)/bin bindir = $(PREFIX)/bin
sbindir = $(PREFIX)/sbin sbindir = $(PREFIX)/sbin
mandir = $(PREFIX)/share/man mandir = $(PREFIX)/share/man
man3dir = $(mandir)/man3
man8dir = $(mandir)/man8 man8dir = $(mandir)/man8
incdir = $(PREFIX)/include incdir = $(PREFIX)/include
libdir = $(PREFIX)/lib libdir = $(PREFIX)/lib

6
lib/Module.mk
View File

@ -1,6 +1,6 @@
# I2C library for Linux # I2C library for Linux
# #
# Copyright (C) 2012 Jean Delvare <jdelvare@suse.de>
# Copyright (C) 2012-2020 Jean Delvare <jdelvare@suse.de>
# #
# This program is free software; you can redistribute it and/or modify # This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published # it under the terms of the GNU Lesser General Public License as published
@ -87,7 +87,7 @@ clean-lib:
$(RM) $(addprefix $(LIB_DIR)/,*.o *.ao $(LIB_TARGETS) $(LIB_LINKS)) $(RM) $(addprefix $(LIB_DIR)/,*.o *.ao $(LIB_TARGETS) $(LIB_LINKS))
install-lib: $(addprefix $(LIB_DIR)/,$(LIB_TARGETS)) install-lib: $(addprefix $(LIB_DIR)/,$(LIB_TARGETS))
$(INSTALL_DIR) $(DESTDIR)$(libdir)
$(INSTALL_DIR) $(DESTDIR)$(libdir) $(DESTDIR)$(man3dir)
ifeq ($(BUILD_DYNAMIC_LIB),1) ifeq ($(BUILD_DYNAMIC_LIB),1)
$(INSTALL_PROGRAM) $(LIB_DIR)/$(LIB_SHLIBNAME) $(DESTDIR)$(libdir) $(INSTALL_PROGRAM) $(LIB_DIR)/$(LIB_SHLIBNAME) $(DESTDIR)$(libdir)
$(LN) $(LIB_SHLIBNAME) $(DESTDIR)$(libdir)/$(LIB_SHSONAME) $(LN) $(LIB_SHLIBNAME) $(DESTDIR)$(libdir)/$(LIB_SHSONAME)
@ -96,10 +96,12 @@ endif
ifeq ($(BUILD_STATIC_LIB),1) ifeq ($(BUILD_STATIC_LIB),1)
$(INSTALL_DATA) $(LIB_DIR)/$(LIB_STLIBNAME) $(DESTDIR)$(libdir) $(INSTALL_DATA) $(LIB_DIR)/$(LIB_STLIBNAME) $(DESTDIR)$(libdir)
endif endif
$(INSTALL_DATA) $(LIB_DIR)/libi2c.3 $(DESTDIR)$(man3dir)
uninstall-lib: uninstall-lib:
for library in $(LIB_TARGETS) $(LIB_LINKS) ; do \ for library in $(LIB_TARGETS) $(LIB_LINKS) ; do \
$(RM) $(DESTDIR)$(libdir)/$$library ; done $(RM) $(DESTDIR)$(libdir)/$$library ; done
$(RM) $(DESTDIR)$(man3dir)/libi2c.3
all: all-lib all: all-lib

141
lib/libi2c.3
View File

@ -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
Write Preview
Loading…
Cancel
Save