doc: extend i2c description for pull-up

drivers/include/periph/i2c.h

@@ -15,7 +15,29 @@
  * @file
  * @brief       Low-level I2C peripheral driver interface definition
  *
- * @note The current version of this interface only supports the 7-bit addressing mode.
+ *              The I2C signal lines SDA/SCL need external pull-up resistors which connect 
+ *              the lines to the positive voltage supply Vcc. The minimum and maximum 
+ *              resistances are computed by:
+ *              \f{eqnarray*}{
+ *              R_{min} &=& \frac{V_{DD} - V_{OL(max)}} {I_{OL}}\\
+ *              R_{max} &=& \frac{t_r} {(0.8473 \cdot C_b)}
+ *              \f}<br>
+ *              where:<br>
+ *              \f$ V_{DD} =\f$ Supply voltage,
+ *              \f$ V_{OL(max)} =\f$ Low level voltage,
+ *              \f$ I_{OL} =\f$ Low level output current,
+ *              \f$ t_r =\f$ Signal rise time,
+ *              \f$ C_b =\f$ Bus capacitance <br>
+ *              <br>The pull-up resistors depend on the bus speed. Some typical values are:<br>
+ *              Normal mode:       10k&Omega;<br>
+ *              Fast mode:          2k&Omega;<br>
+ *              Fast plus mode:     2k&Omega;
+ *
+ *              For more details refer to section 7.1 in:<br>
+ *              http://www.nxp.com/documents/user_manual/UM10204.pdf
+ *
+ * @note        The current version of this interface only supports the 
+                7-bit addressing mode.
  *
  * @author      Hauke Petersen <hauke.petersen@fu-berlin.de>
  */