rawi2ctool Files

======== rawi2ctool help ===========

./rawi2ctool version 3.0

Copyright (C) 1997-2015  Gilles Buloz

#################### WARNING ####################################
This program comes with ABSOLUTELY NO WARRANTY.
IT CAN BE EXTREMELY DANGEROUS IF USED IMPROPERLY : it can confuse
your I2C bus, cause data loss, or have more serious side effects.
#################################################################

Its purpose is to do raw I2C accesses to a bus, IF SUPPORTED BY THE ADAPTER,
to probe the bus, read or write some data, detect glitches, do a bench,
program an EEPROM with the required blocksize, test the I2C bus driver, ...

Raw I2C mode enables data frames that are not supported by SMBus and its
related tools.

USAGE :
 Read :
  ./rawi2ctool [options] /dev/i2c-x I2C_addr r offset offset_byte_count byte_count
  ./rawi2ctool [options] /dev/i2c-x I2C_addr r offset offset_byte_count byte_count -
 Write :
  ./rawi2ctool [options] /dev/i2c-x I2C_addr w offset offset_byte_count byte ...
  ./rawi2ctool [options] /dev/i2c-x I2C_addr w offset offset_byte_count -
 Probe :
  ./rawi2ctool [options] /dev/i2c-x p [<start_addr> [<end_addr>]]

offset :
    the offset where to write in the chip;
offset_byte_count :
    the length of the offset in bytes (0 to 4); usually 1 (sensors or less
    than 4KB EEPROMs) or 2 (for bigger EEPROMs). if 0, no offset data is sent.
stdin/stdout :
    when "-" is used as last parameter (as shown above) the data to write is
    read in raw binary format from stdin, or the data read is written in raw
    binary format to stdout.

Returns a non 0 value on error.

OPTIONS :
-b <size> : blocksize to use on I2C (default = datasize : all data in one block).
            The data to read or write is split into several chunks (separed by a
            stop) according to the following rules:
            - without -B : insert a stop each time the offset accessed is reaching
                           a blocksize alignment boundary. This is required when
                           writing to an EEPROM (page write) where the blocksize
                           must match the EEPROM internal page write buffer size
                           (or be a lower power of two).
            - with    -B : insert a stop each time blocksize bytes of data are
                           transfered, possibly crossing a blocksize alignment
                           boundary.
            In both cases, each chunk starts with a start followed by the offset
            to access, so that concurrent/interleaved accesses to the target
            device are allowed.

-B        : To use with -b (see above).

-D <usec> : Insert a delay after each block transfered (in microseconds). This
            may be needed for debug purposes. See also options -r and -t.
            This delay is made with usleep() so it is NOT accurate.

-g        : Detect glitches leading to data corruption. To be used for a read
            access with -l option.
            An additional initial read is done, then data read at each
            subsequent iteration is compared with the initial one.
            Even if this option is only available when reading the device, the
            write accesses to the device are also checked because an address
            and offset is written to initiate each read.
            It is recommended :
            - to have the device containing a pattern or some data not all at
              00 or FF (write some data before test if needed) to detect 
              unexpected 0 or 1 bits.
            - to choose a non null offset to test corruption while writing the
              offset.
            - to use a byte_count of only some bytes to have as much write
              (I2C addr + offset) than read (data).

-i        : Call ioctl to set bus retries and timeout (see -r and -t) instead of
            emulating them by calling ioctl as many times as required.
            WARNING : this affects all other processes using the same I2C bus.

-l <count>: Repeat the command as many time as specified (loop).
            This is useful for read bench purposes : set a blocksize to read as
            many bytes as required in one burst, use quiet mode to prevent the
            messages from slowing down the test, then repeat with this option
            to run during several seconds, and measure the execution time of
            this command with the "time" command.
            Can also be used for write bench purposes, but take care not exceed
            the maximum write cycles of the device. Can also be used to check if
            the I2C driver correctly handles the retries parameter (see below).

-n        : Does nothing. Obsolete option for backward compatibility (was to
            disable retries and timeout settings using ioctl, which is now
            disabled by default). See also option -i.

-p        : PREVIEW what will be done on the bus without actually doing something
            (DRY RUN), except opening the I2C device file. In this mode, it is
            obvious that the data returned when reading is a dummy one.

-q        : Quiet mode. No message is displayed nor data dump. This speeds-up
            things when used on a serial console. When reading some data, the
            raw binary output data can still be sent to stdout by appending a
            "-" at the end of the command.

-r        : Set the retry count parameter. Default = 1 for a probe, else 10000.
            This parameter is used to retry the I2C accesses until an ACK is
            aserted by a device (for ex. an EEPROM that was busy while storing
            some data just written to it).
            It is also used to retry when the arbitration is lost on a
            multimaster bus.
            With option -i, this parameter is used for the ioctl I2C_RETRIES
            that impacts all accesses made by the adapter.

-t        : Set the timeout parameter in units of 10mS. Default = 10 x 10mS.
            Without option -i, this parameter is used along with the -r above
            (retries stop when the retry count is reached or timeout expired).
            With option -i, this parameter is used for the ioctl I2C_TIMEOUT
            that impacts all accesses made by the adapter and sets the maximum
            duration allowed for a data transfer (in case of clock stretching),
            or for retries when arbitration is lost.
            It is not used to retry for an ACK.

EXAMPLES :

Probe bus /dev/i2c-3
  ./rawi2ctool /dev/i2c-3 p

Read 0x10 bytes from a 4KB or more EEPROM, at I2C addr 0x52, at (2 bytes) offset 7
  ./rawi2ctool /dev/i2c-2 0x52 r 0x7 2 0x10

Read 0x8 bytes from a less than 4KB EEPROM, at I2C addr 0x52, at (1 bytes) offset 7
  ./rawi2ctool /dev/i2c-2 0x52 r 0x7 1 0x8

Read 1 byte from sensor at I2C addr 0x48 at (1 byte) offset 0 in device
  ./rawi2ctool /dev/i2c-2 0x48 r 0x0 1 1

Write 0x5A (1 byte) to sensor at I2C addr 0x48 at (1 byte) offset 4 in device
  ./rawi2ctool /dev/i2c-2 0x48 w 4 1 0x5A

Write 4 bytes to a 4KB or more EEPROM, at I2C addr 0x50, at (2 bytes) offset 0x102
in device (no need for blocksize as this access do not cross a page write boundary)
  ./rawi2ctool /dev/i2c-2 0x50 w 0x102 2 0x11 0x3e 0x4f 0x70

Write 3 bytes to a less than 4KB EEPROM, at I2C addr 0x50, at (1 byte) offset 0x2c
in device (also no blocksize needed)
  ./rawi2ctool /dev/i2c-2 0x50 w 0x2c 1 0x11 0x3e 0x4f

Write a file to a 4KB or more EEPROM with blocksize 32 at (2 bytes) offset 0x10
  cat random.bin | ./rawi2ctool -b 32 /dev/i2c-2 0x52 w 0x10 2 -

Do the same on an interface not correctly supporting retries/timeout, by using a
delay of 10mS after each block (page) written
  cat random.bin | ./rawi2ctool -D 10000 -b 32 /dev/i2c-2 0x52 w 0x10 2 -

Write a string to a less that 4KB EEPROM with blocksize 16 at (1 byte) offset 0x1C
  echo -n "the string to write" | ./rawi2ctool -b 16 /dev/i2c-0 0x51 w 0x1c 1 -

Read 4096 bytes at offset 0x7e from a 4KB or more EEPROM and write to a file
  ./rawi2ctool -q /dev/i2c-0 0x56 r 0x7e 2 4096 - > dump.bin

Read 0x100 bytes at offset 0 from a 4KB or more EEPROM and use xxd for dump
  ./rawi2ctool -q /dev/i2c-22 0x52 r 0x0 2 0x100 - | xxd

Bench read accesses for 100 x 1024 bytes blocks
  time ./rawi2ctool -q -b 1024 -l 100 /dev/i2c-0 0x56 r 0 2 1024

Bench write accesses for 100 x 1024 bytes using 64 bytes blocks
  dd if=/dev/urandom bs=1 count=1024 of=random.bin
  time cat random.bin | ./rawi2ctool -q -b 64 -l 100 /dev/i2c-0 0x51 w 0 2 -

Detect glitches on a temperature sensor, writing 5A to scratchpad register 4 first
  ./rawi2ctool /dev/i2c-2 0x4b w 4 1 0x5A
  ./rawi2ctool -q -g -l 10000 /dev/i2c-2 0x4b r 4 1 1


======== V3.0 compared to V2.0 ==========

- By default, no more set I2C bus retries and timeout using I2C_RETRIES and
  I2C_TIMEOUT ioctls, but manage retries and timeout in the application so
  than the other prgrams using the bus are not disturbed. Use new option -i
  to force use of ioctls. Option -n that was disabling ioctls is now
  obsolete and does nothing (for compatibility).
- Display errors other than "No ACK" (ENXIO) when probing (arbitration lost,
  bus not supporting raw I2C, ...)