drivers/periph: reworked I2C driver

- removed read_byte and read_reg
- moved bus speed parameter to i2c_acquire
- made parameters overridable
- added fixed return codes
- added default type

drivers/include/periph/i2c.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014-2015 Freie Universität Berlin
+ * Copyright (C) 2014-2016 Freie Universität Berlin
  *
  * This file is subject to the terms and conditions of the GNU Lesser
  * General Public License v2.1. See the file LICENSE in the top level
@@ -51,16 +51,14 @@
  * @author      Thomas Eichinger <thomas.eichinger@fu-berlin.de>
  */
 
-#ifndef I2C_H
-#define I2C_H
+#ifndef PERIPH_I2C_H
+#define PERIPH_I2C_H
 
 #include <stdint.h>
 
+#include "periph_conf.h"
 #include "periph_cpu.h"
-/**
- * @todo    Remove dev_enums.h include once all platforms are ported to the
- *          updated periph interface
- */
+/* TODO: remove once all platforms are ported to this interface */
 #include "periph/dev_enums.h"
 
 #ifdef __cplusplus
@@ -120,16 +118,23 @@ typedef enum {
 /** @} */
 
 /**
- * @brief   Initialize an I2C device to run as bus master
+ * @brief   I2C error codes
+ */
+enum {
+    I2C_OK       = 0,       /**< everything went fine */
+    I2C_ERR_ADDR = -1,      /**< address error */
+    I2C_ERR_DATA = -2       /**< data error */
+};
+
+/**
+ * @brief   Initialize an I2C buses pins
  *
  * @param[in] dev           the device to initialize
- * @param[in] speed         the selected bus speed
  *
  * @return                  0 on successful initialization
  * @return                  -1 on undefined device given
- * @return                  -2 on unsupported speed value
  */
-int i2c_init_master(i2c_t dev, i2c_speed_t speed);
+int i2c_init(i2c_t dev);
 
 /**
  * @brief   Get mutually exclusive access to the given I2C bus
@@ -140,147 +145,110 @@ int i2c_init_master(i2c_t dev, i2c_speed_t speed);
  * @param[in] dev       I2C device to access
  *
  * @return              0 on success
- * @return              -1 on error
+ * @return              -1 on invalid device
+ * @return              -2 on unsupported speed value
  */
-int i2c_acquire(i2c_t dev);
+int i2c_acquire(i2c_t dev, i2c_speed_t speed);
 
 /**
  * @brief   Release the given I2C device to be used by others
  *
  * @param[in] dev       I2C device to release
- *
- * @return              0 on success
- * @return              -1 on error
- */
-int i2c_release(i2c_t dev);
-
-/**
- * @brief   Read one byte from an I2C device with the given address
- *
- * @param[in]  dev          I2C peripheral device
- * @param[in]  address      bus address of the target device
- * @param[out] data         the result that was read
- *
- * @return                  the number of bytes that were read
- * @return                  -1 on undefined device given
- * @return                  -2 on invalid address
  */
-int i2c_read_byte(i2c_t dev, uint8_t address, char *data);
+void i2c_release(i2c_t dev);
 
 /**
- * @brief   Read multiple bytes from an I2C device with the given address
+ * @brief   Read data from an I2C device with the given address
  *
  * @param[in]  dev          I2C peripheral device
- * @param[in]  address      bus address of the target device
+ * @param[in]  addr         7-bit device address (right-aligned)
  * @param[out] data         array holding the received bytes
  * @param[in]  length       the number of bytes to read into `data`
  *
- * @return                  the number of bytes that were read
- * @return                  -1 on undefined device given
- */
-int i2c_read_bytes(i2c_t dev, uint8_t address, char *data, int length);
-
-/**
- * @brief   Read one byte from a register at the I2C slave with the given
- *          address
- *
- * @param[in]  dev          I2C peripheral device
- * @param[in]  address      bus address of the target device
- * @param[in]  reg          the register address on the targeted I2C device
- * @param[out] data         the result that was read
- *
- * @return                  the number of bytes that were read
- * @return                  -1 on undefined device given
+ * @return                  I2C_OK on successful transfer of @p len byte
+ * @return                  I2C_ERR_ADDR on address error
+ * @return                  I2C_ERR_DATA on data error
  */
-int i2c_read_reg(i2c_t dev, uint8_t address, uint8_t reg, char *data);
+int i2c_read(i2c_t dev, uint8_t addr, uint8_t *data, size_t len);
 
 /**
- * @brief   Read multiple bytes from a register at the I2C slave with the given
- *          address
+ * @brief   Read data from a specified register
  *
  * @param[in]  dev          I2C peripheral device
- * @param[in]  address      bus address of the target device
+ * @param[in]  addr         7-bit device address (right-aligned)
  * @param[in]  reg          the register address on the targeted I2C device
  * @param[out] data         array holding the received bytes
- * @param[in]  length       the number of bytes to read into `data`
+ * @param[in]  len          number of bytes to read into `data
  *
- * @return                  the number of bytes that were read
- * @return                  -1 on undefined device given
+ * @return                  I2C_OK on successful transfer of @p len byte
+ *                          to @p reg
+ * @return                  I2C_ERR_ADDR on address error
+ * @return                  I2C_ERR_DATA on data error
  */
-int i2c_read_regs(i2c_t dev, uint8_t address, uint8_t reg,
-                  char *data, int length);
+int i2c_read_reg(i2c_t dev, uint8_t addr, uint8_t reg,
+                 uint8_t *data, size_t len);
 
 /**
  * @brief   Write one byte to an I2C device with the given address
  *
  * @param[in] dev           I2C peripheral device
- * @param[in] address       bus address of the target device
+ * @param[in] addr          7-bit device address (right-aligned)
  * @param[in] data          byte to write to the device
  *
- * @return                  the number of bytes that were written
- * @return                  -1 on undefined device given
+ * @return                  I2C_OK on successful transfer of @p data
+ * @return                  I2C_ERR_ADDR on address error
+ * @return                  I2C_ERR_DATA on data error
  */
-int i2c_write_byte(i2c_t dev, uint8_t address, char data);
+int i2c_write_byte(i2c_t dev, uint8_t addr, uint8_t data);
 
 /**
  * @brief   Write multiple bytes to an I2C device with the given address
  *
  * @param[in] dev           I2C peripheral device
- * @param[in] address       bus address of the target device
+ * @param[in] addr          7-bit device address (right-aligned)
  * @param[in] data          array with bytes to write to the target device
- * @param[in] length        number of bytes to write to the target device
+ * @param[in] len           number of bytes to write to the target device
  *
- * @return                  the number of bytes that were written
- * @return                  -1 on undefined device given
+ * @return                  I2C_OK on successful transfer of @p len byte
+ * @return                  I2C_ERR_ADDR on address error
+ * @return                  I2C_ERR_DATA on data error
  */
-int i2c_write_bytes(i2c_t dev, uint8_t address, char *data, int length);
+int i2c_write_bytes(i2c_t dev, uint8_t addr, uint8_t *data, size_t len);
 
 /**
  * @brief   Write one byte to a register at the I2C slave with the given address
  *
  * @param[in] dev           I2C peripheral device
- * @param[in] address       bus address of the target device
+ * @param[in] addr          7-bit device address (right-aligned)
  * @param[in] reg           the register address on the targeted I2C device
  * @param[in] data          byte to write to the device
  *
- * @return                  the number of bytes that were written
- * @return                  -1 on undefined device given
+ * @return                  I2C_OK on successful transfer of @p data to @p reg
+ * @return                  I2C_ERR_ADDR on address error
+ * @return                  I2C_ERR_DATA on data error
  */
-int i2c_write_reg(i2c_t dev, uint8_t address, uint8_t reg, char data);
+int i2c_write_reg(i2c_t dev, uint8_t addr, uint8_t reg, uint8_t data);
 
 /**
  * @brief   Write multiple bytes to a register at the I2C slave with the given
  *          address
  *
  * @param[in] dev           I2C peripheral device
- * @param[in] address       bus address of the target device
+ * @param[in] addr          7-bit device address (right-aligned)
  * @param[in] reg           the register address on the targeted I2C device
  * @param[in] data          array with bytes to write to the target device
- * @param[in] length        number of bytes to write to the target device
+ * @param[in] len           number of bytes to write to the target device
  *
- * @return                  the number of bytes that were written
- * @return                  -1 on undefined device given
- */
-int i2c_write_regs(i2c_t dev, uint8_t address, uint8_t reg,
-                   char *data, int length);
-
-/**
- * @brief   Power on the given I2C peripheral
- *
- * @param[in] dev           the I2C device to power on
+ * @return                  I2C_OK on successful transfer of @p len byte
+ *                          to @p reg
+ * @return                  I2C_ERR_ADDR on address error
+ * @return                  I2C_ERR_DATA on data error
  */
-void i2c_poweron(i2c_t dev);
-
-/**
- * @brief   Power off the given I2C peripheral
- *
- * @param[in] dev           the I2C device to power off
- */
-void i2c_poweroff(i2c_t dev);
-
+int i2c_write_regs(i2c_t dev, uint8_t addr, uint8_t reg,
+                   uint8_t *data, size_t len);
 #ifdef __cplusplus
 }
 #endif
 
-#endif /* I2C_H */
+#endif /* PERIPH_I2C_H */
 /** @} */