i2c-tools: Add examples to manual pages As suggested by rpjday back in August. I tried to follow the same style Wolfram used for the i2ctransfer examples, for consistency.
diff --git a/tools/i2cdetect.8 b/tools/i2cdetect.8 index afd6c3b..81d0f97 100644 --- a/tools/i2cdetect.8 +++ b/tools/i2cdetect.8
@@ -1,4 +1,4 @@ -.TH I2CDETECT 8 "April 2008" +.TH I2CDETECT 8 "October 2017" .SH NAME i2cdetect \- detect I2C chips @@ -81,6 +81,38 @@ .B "\-l" Output a list of installed busses. +.SH EXAMPLES +.PP +List all available I2C busses: +.nf +.RS +# i2cdetect -l +.RE +.fi +.PP +Immediately scan the standard addresses on I2C bus 9 (i2c-9), using the +default method for each address (no user confirmation): +.nf +.RS +# i2cdetect -y 9 +.RE +.fi +.PP +Query the functionalities of I2C bus 1 (i2c-1): +.nf +.RS +# i2cdetect -F 1 +.RE +.fi +.PP +Scan addresses 0x10 to 0x17 on the I2C bus named "SMBus I801 adapter at efa0", +using the "receive byte" method, after user confirmation: +.nf +.RS +# i2cdetect -r "SMBus I801 adapter at efa0" 0x10 0x17 +.RE +.fi + .SH SEE ALSO i2cdump(8), i2cget(8), i2cset(8), i2ctransfer(8), sensors-detect(8)
diff --git a/tools/i2cdump.8 b/tools/i2cdump.8 index a5490e6..fb7217e 100644 --- a/tools/i2cdump.8 +++ b/tools/i2cdump.8
@@ -1,4 +1,4 @@ -.TH I2CDUMP 8 "May 2008" +.TH I2CDUMP 8 "October 2017" .SH NAME i2cdump \- examine I2C registers @@ -74,6 +74,44 @@ knowledge of the chip you're working with and an idea of what you are looking for. +.SH EXAMPLES +.PP +Dump the whole contents of I2C device at 7-bit address 0x50 on bus 9 +(i2c-9), using the default read method (byte mode), after user confirmation: +.nf +.RS +# i2cdump 9 0x50 +.RE +.fi +.PP +Immediately dump the whole contents of I2C device at 7-bit address 0x50 on +bus 9 (i2c-9), using I2C block read transactions (no user confirmation): +.nf +.RS +# i2cdump -y 9 0x50 i +.RE +.fi +If the device is an EEPROM, the output would typically be the same as output +of the previous example. +.PP +Dump registers 0x00 to 0x3f of the I2C device at 7-bit address 0x2d on +bus 1 (i2c-1), using the default read method (byte mode), after user +confirmation: +.nf +.RS +# i2cdump -r 0x00-0x3f 1 0x2d +.RE +.fi +.PP +Dump the registers of the SMBus device at address 0x69 on bus 0 (i2c-0), +using one SMBus block read transaction with error checking enabled, after +user confirmation: +.nf +.RS +# i2cdump 0 0x69 sp +.RE +.fi + .SH SEE ALSO i2cdetect(8), i2cget(8), i2cset(8), i2ctransfer(8), isadump(8)
diff --git a/tools/i2cget.8 b/tools/i2cget.8 index 2105cad..a1a1276 100644 --- a/tools/i2cget.8 +++ b/tools/i2cget.8
@@ -1,4 +1,4 @@ -.TH I2CGET 8 "May 2008" +.TH I2CGET 8 "October 2017" .SH "NAME" i2cget \- read from I2C/SMBus chip registers @@ -58,6 +58,57 @@ certain chips. This is particularly true if setting \fImode\fR to \fBcp\fP (write byte/read byte with PEC). Be extremely careful using this program. +.SH EXAMPLES +.PP +Get the value of 8-bit register 0x11 of the I2C device at 7-bit address 0x2d +on bus 1 (i2c-1), after user confirmation: +.nf +.RS +# i2cget 1 0x2d 0x11 +.RE +.fi +.PP +Get the value of 16-bit register 0x00 of the I2C device at 7-bit address 0x48 +on bus 1 (i2c-1), after user confirmation: +.nf +.RS +# i2cget 1 0x48 0x00 w +.RE +.fi +.PP +Set the internal pointer register of a 24C02 EEPROM at 7-bit address 0x50 +on bus 9 (i2c-9) to 0x00, then read the first 2 bytes from that EEPROM: +.nf +.RS +# i2cset -y 9 0x50 0x00 ; i2cget -y 9 0x50 ; i2cget -y 9 0x50 +.RE +.fi +This assumes that the device automatically increments its internal pointer +register on every read, and supports read byte transactions (read without +specifying the register address, "Receive Byte" in SMBus terminology.) +Most EEPROM devices behave that way. Note that this is only safe as long as +nobody else is accessing the I2C device at the same time. A safer approach +would be to use a "Read Word" SMBus transaction instead, or an I2C Block +Read transaction to read more than 2 bytes. +.PP +Set the internal pointer register of a 24C32 EEPROM at 7-bit address 0x53 +on bus 9 (i2c-9) to 0x0000, then read the first 2 bytes from that EEPROM: +.nf +.RS +# i2cset -y 9 0x53 0x00 0x00 ; i2cget -y 9 0x53 ; i2cget -y 9 0x53 +.RE +.fi +This again assumes that the device automatically increments its internal +pointer register on every read, and supports read byte transactions. While +the previous example was for a small EEPROM using 8-bit internal addressing, +this example is for a larger EEPROM using 16-bit internal addressing. Beware +that running this command on a small EEPROM using 8-bit internal addressing +would actually \fIwrite\fR 0x00 to the first byte of that EEPROM. The safety +concerns raised above still stand, however in this case there is no SMBus +equivalent, so this is the only way to read data from a large EEPROM if your +master isn't fully I2C capable. With a fully I2C capable master, you would +use \fIi2ctransfer\fR to achieve the same in a safe and faster way. + .SH SEE ALSO i2cdetect(8), i2cdump(8), i2cset(8), i2ctransfer(8)
diff --git a/tools/i2cset.8 b/tools/i2cset.8 index 734bbd7..19887bd 100644 --- a/tools/i2cset.8 +++ b/tools/i2cset.8
@@ -1,4 +1,4 @@ -.TH I2CSET 8 "November 2008" +.TH I2CSET 8 "October 2017" .SH "NAME" i2cset \- set I2C registers @@ -92,6 +92,35 @@ DESTROY your memory, leaving your system unbootable! Be extremely careful using this program. +.SH EXAMPLES +.PP +Write value 0x42 to 8-bit register 0x11 of the I2C device at 7-bit +address 0x2d on bus 1 (i2c-1), after user confirmation: +.nf +.RS +# i2cset 1 0x2d 0x11 0x42 +.RE +.fi +.PP +Immediately clear the 3 least significant bits of 8-bit register 0x11 of the +I2C device at 7-bit address 0x2d on bus 1 (i2c-1) (no user confirmation): +.nf +.RS +# i2cset -y -m 0x07 1 0x2d 0x11 0x00 +.RE +.fi +.PP +Write value 0x5000 to 16-bit register 0x02 of the I2C device at 7-bit +address 0x48 on bus 1 (i2c-1), after user confirmation: +.nf +.RS +# i2cset 1 0x48 0x02 0x5000 w +.RE +.fi +.PP +Also see i2cget(8) for examples of combined usage of \fIi2cset\fR and +\fIi2cget\fR. + .SH SEE ALSO i2cdetect(8), i2cdump(8), i2cget(8), i2ctransfer(8), isaset(8)