From cdb9eefc6426583c0a52997362b5250effe59926 Mon Sep 17 00:00:00 2001 From: Jean Delvare Date: Tue, 8 Sep 2020 17:22:38 +0200 Subject: 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 --- Makefile | 1 + lib/Module.mk | 6 ++- lib/libi2c.3 | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 146 insertions(+), 2 deletions(-) create mode 100644 lib/libi2c.3 diff --git a/Makefile b/Makefile index dc56383..e784921 100644 --- a/Makefile +++ b/Makefile @@ -12,6 +12,7 @@ PREFIX ?= /usr/local bindir = $(PREFIX)/bin sbindir = $(PREFIX)/sbin mandir = $(PREFIX)/share/man +man3dir = $(mandir)/man3 man8dir = $(mandir)/man8 incdir = $(PREFIX)/include libdir = $(PREFIX)/lib diff --git a/lib/Module.mk b/lib/Module.mk index 6727de7..0907f1a 100644 --- a/lib/Module.mk +++ b/lib/Module.mk @@ -1,6 +1,6 @@ # I2C library for Linux # -# Copyright (C) 2012 Jean Delvare +# Copyright (C) 2012-2020 Jean Delvare # # 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 @@ -87,7 +87,7 @@ clean-lib: $(RM) $(addprefix $(LIB_DIR)/,*.o *.ao $(LIB_TARGETS) $(LIB_LINKS)) install-lib: $(addprefix $(LIB_DIR)/,$(LIB_TARGETS)) - $(INSTALL_DIR) $(DESTDIR)$(libdir) + $(INSTALL_DIR) $(DESTDIR)$(libdir) $(DESTDIR)$(man3dir) ifeq ($(BUILD_DYNAMIC_LIB),1) $(INSTALL_PROGRAM) $(LIB_DIR)/$(LIB_SHLIBNAME) $(DESTDIR)$(libdir) $(LN) $(LIB_SHLIBNAME) $(DESTDIR)$(libdir)/$(LIB_SHSONAME) @@ -96,10 +96,12 @@ endif ifeq ($(BUILD_STATIC_LIB),1) $(INSTALL_DATA) $(LIB_DIR)/$(LIB_STLIBNAME) $(DESTDIR)$(libdir) endif + $(INSTALL_DATA) $(LIB_DIR)/libi2c.3 $(DESTDIR)$(man3dir) uninstall-lib: for library in $(LIB_TARGETS) $(LIB_LINKS) ; do \ $(RM) $(DESTDIR)$(libdir)/$$library ; done + $(RM) $(DESTDIR)$(man3dir)/libi2c.3 all: all-lib 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 +.\" 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 +.B #include + +/* 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 +. + +.SH AUTHOR +Simon G. Vogl, Frodo Looijaard, Jean Delvare and others -- cgit v1.2.1