Bcm2835 i2c bug
The I2C module in the BCM2835 SOC has a bug.
In most protocols the master device will dictate the speed of communiciation. I2C is a bit smarter in that a slave can ask the master to slow down. This mechanism is called clock stretching.
Signals on the I2C bus are never driven "high" by any bus-device. There is a passive pullup that creates the "high" level, and bus-devices can pull the signals low. Clock stretching works by the slave pulling the clock signal low during the time that it is not yet ready to recieve the next clock pulse. A master should check that the clock signal has become high before proceding with the next clock pulse.
The problem with the BCM2835 is that it checks if the clock signal has become "high" just nanonseconds before it would normally pull the clock signal low. If it determines that the clock signal is low, it will proceed by trying again a bit later. Clock stretching as it is supposed to work. When the slave does not do clock stretching the BCM2835 will see a high, and proceed to pull the clock signal low. Also good.
However, bad things can happen when the slave does clock stretching but is ready just nanoseconds before the BCM2835 checks the signal. The clock signal will go high, the BCM2835 sees a high signal and proceeds with pulling the signal low again shortly thereafter. The "high" period of the clock pulse can then be as short as 80 ns.
For the bitwizard I2C boards this is a problem: Short pulses on the SCL line are filtered out as "glitches". So whereas the BCM2835 then thinks it is providing the next "low" SCL period, our board still sees the previous clock-low-period. Master and slave are desynchronized and this leads to problems (i.e. our board seeing a different datavalue, our board not sending an ACK because it expects another bit, and the actual ACK extending into the "bus idle" period that follows a transaction (this foils the "start" condition of the next transactions)).
This is hardware-bug in the BCM2835.
What can be done about this?
Not much: It is a hardware bug. You can't upgrade the existing hardware without making new chips.
The BitWizard I2C boards now time the release of the SCL signal about 5 (or 15) microseconds after the clock edge. This puts the release about 5 microseconds away from the sampling and reassertion of the SCL signal by the BCM2835. Although the 5 microsecond clock pulse is officially way out of spec for a 100kHz I2C bus, it is reliably detected by our hardware.
The consequence of this is however that we have to assume a 100kHz clock. If the clock is not 100kHz, the BCM2835 bug might be triggered.
So... Due to a bug in the BCM2835 SOC hardware, it is strongly recommended to use the default 100kHz clock and nothing else.