added utils

rpi/stm32flash/I2C.txt

@@ -0,0 +1,108 @@
+About I2C back-end communication in stm32flash
+==========================================================================
+
+Starting from version v0.4, beside the serial communication port,
+stm32flash adds support for I2C port to talk with STM32 bootloader.
+
+The current I2C back-end supports only the API provided by Linux kernel
+driver "i2c-dev", so only I2C controllers with Linux kernel driver can be
+used.
+In Linux source code, most of the drivers for I2C and SMBUS controllers
+are in
+	./drivers/i2c/busses/
+Only I2C is supported by STM32 bootloader, so check the section below
+about SMBUS.
+No I2C support for Windows is available in stm32flash v0.4.
+
+Thanks to the new modular back-end, stm32flash can be easily extended to
+support new back-ends and API. Check HOWTO file in stm32flash source code
+for details.
+
+In the market there are several USB-to-I2C dongles; most of them are not
+supported by kernel drivers. Manufacturer provide proprietary userspace
+libraries using not standardized API. Such API and dongles could in
+principle be supported in feature versions of stm32flash.
+
+The open-hardware i2c-tiny-usb device and its reimplementation on the
+STM32, the i2c-star, are fully supported by the Linux kernel.
+- https://www.fischl.de/i2c-mp-usb/
+- https://github.com/daniel-thompson/i2c-star
+
+There is also the I2CDriver which has open-source drivers and
+available design files. Although there is no kernel driver,
+there is a userspace compatibility interface available.
+- https://github.com/jamesbowman/i2cdriver
+- https://github.com/mbenkmann/i2cdriver/tree/master/c/linux
+
+There are currently 3 versions of STM32 bootloader for I2C communications:
+- v1.0 using I2C clock stretching synchronization between host and STM32;
+- v1.1 superset of v1.0, adds non stretching commands;
+- v1.2 superset of v1.1, adds CRC command and compatibility with i2cdetect.
+Details in ST application note AN2606.
+All the bootloaders above are tested and working with stm32flash.
+
+
+SMBUS controllers
+==========================================================================
+
+Almost 50% of the drivers in Linux source code folder
+	./drivers/i2c/busses/
+are for controllers that "only" support SMBUS protocol. They can NOT
+operate with STM32 bootloader.
+To identify if your controller supports I2C, use command:
+	i2cdetect -F n
+where "n" is the number of the I2C interface (e.g. n=3 for "/dev/i2c-3").
+Controllers that supports I2C will report
+	I2C yes
+Controller that support both I2C and SMBUS are ok.
+
+If you are interested on details about SMBUS protocol, you can download
+the current specs from
+	http://smbus.org/specs/smbus20.pdf
+and you can read the files in Linux source code
+	./Documentation/i2c/i2c-protocol
+	./Documentation/i2c/smbus-protocol
+
+
+About bootloader v1.0
+==========================================================================
+
+(Used on F0, F3 and F4 up to STM32F401xB(C) devices)
+
+Version v1.0 can have issues with some I2C controllers due to use of clock
+stretching during commands that require long operations, like flash erase
+and programming.
+
+Clock stretching is a technique to synchronize host and I2C device. When
+I2C device wants to force a delay in the communication, it push "low" the
+I2C clock; the I2C controller detects it and waits until I2C clock returns
+"high".
+Most I2C controllers set a "timeout" for clock stretching, ranging from
+few milli-seconds to seconds depending on specific HW or SW driver.
+
+It is possible that the timeout in your I2C controller is smaller than the
+delay required for flash erase or programming. In this case the I2C
+controller will timeout and report error to stm32flash.
+There is no possibility for stm32flash to retry, so it can only signal the
+error and exit.
+
+To by-pass the issue with bootloader v1.0 you can modify the kernel driver
+of your I2C controller. Not an easy job, since every controller has its own
+way to handle the timeout.
+
+In my case I'm using the I2C controller integrated in the VGA port of my
+laptop HP EliteBook 8460p. I built the 0.25$ VGA-to-I2C adapter reported in
+https://web.archive.org/web/20160506154718/http://www.paintyourdragon.com/?p=43
+
+To change the timeout of the I2C controller I had to modify the kernel file
+	drivers/gpu/drm/radeon/radeon_i2c.c
+line 969
+- i2c->bit.timeout = usecs_to_jiffies(2200);      /* from VESA */
++ i2c->bit.timeout = msecs_to_jiffies(5000);      /* 5s for STM32 */
+and recompile it.
+Then
+	$> modprobe i2c-dev
+	$> chmod 666 /dev/i2c-7
+	#> stm32flash -a 0x39 /dev/i2c-7
+
+2014-09-16 Antonio Borneo