From a867aeaba2c306d1375f73649d9ca8fff71c4af9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Joakim=20Nohlg=C3=A5rd?= <joakim.nohlgard@eistec.se>
Date: Wed, 28 Nov 2018 08:43:01 +0100
Subject: [PATCH] periph/i2c: Add precondition on i2c_acquire for i2c bus
 access

---
 drivers/include/periph/i2c.h | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/drivers/include/periph/i2c.h b/drivers/include/periph/i2c.h
index 3a638d2839..42bcf1be2b 100644
--- a/drivers/include/periph/i2c.h
+++ b/drivers/include/periph/i2c.h
@@ -243,6 +243,8 @@ int i2c_release(i2c_t dev);
  * @note    This function is using a repeated start sequence for reading from
  *          the specified register address.
  *
+ * @pre     i2c_acquire must be called before accessing the bus
+ *
  * @param[in]  dev          I2C peripheral device
  * @param[in]  reg          register address to read from (8- or 16-bit,
  *                          right-aligned)
@@ -269,6 +271,8 @@ int i2c_read_reg(i2c_t dev, uint16_t addr, uint16_t reg,
  * @note    This function is using a repeated start sequence for reading from
  *          the specified register address.
  *
+ * @pre     i2c_acquire must be called before accessing the bus
+ *
  * @param[in]  dev          I2C peripheral device
  * @param[in]  reg          register address to read from (8- or 16-bit,
  *                          right-aligned)
@@ -294,6 +298,8 @@ int i2c_read_regs(i2c_t dev, uint16_t addr, uint16_t reg,
  * @note    This function is using a repeated start sequence for reading from
  *          the specified register address.
  *
+ * @pre     i2c_acquire must be called before accessing the bus
+ *
  * @param[in]  dev          I2C peripheral device
  * @param[in]  addr         7-bit or 10-bit device address (right-aligned)
  * @param[out] data         memory location to store received data
@@ -316,6 +322,8 @@ int i2c_read_byte(i2c_t dev, uint16_t addr, void *data, uint8_t flags);
  * @note    This function is using a repeated start sequence for reading from
  *          the specified register address.
  *
+ * @pre     i2c_acquire must be called before accessing the bus
+ *
  * @param[in]  dev          I2C peripheral device
  * @param[in]  addr         7-bit or 10-bit device address (right-aligned)
  * @param[out] data         memory location to store received data
@@ -337,6 +345,8 @@ int i2c_read_bytes(i2c_t dev, uint16_t addr,
 /**
  * @brief   Convenience function for writing a single byte onto the bus
  *
+ * @pre     i2c_acquire must be called before accessing the bus
+ *
  * @param[in] dev           I2C peripheral device
  * @param[in] addr          7-bit or 10-bit device address (right-aligned)
  * @param[in] data          byte to write to the device
@@ -355,6 +365,8 @@ int i2c_write_byte(i2c_t dev, uint16_t addr, uint8_t data, uint8_t flags);
 /**
  * @brief   Convenience function for writing several bytes onto the bus
  *
+ * @pre     i2c_acquire must be called before accessing the bus
+ *
  * @param[in] dev           I2C peripheral device
  * @param[in] addr          7-bit or 10-bit device address (right-aligned)
  * @param[in] data          array holding the bytes to write to the device
@@ -379,6 +391,8 @@ int i2c_write_bytes(i2c_t dev, uint16_t addr, const void *data,
  * @note    This function is using a repeated start sequence for writing to the
  *          specified register address.
  *
+ * @pre     i2c_acquire must be called before accessing the bus
+ *
  * @param[in]  dev          I2C peripheral device
  * @param[in]  reg          register address to read from (8- or 16-bit,
  *                          right-aligned)
@@ -403,6 +417,8 @@ int i2c_write_reg(i2c_t dev, uint16_t addr, uint16_t reg,
  * @note    This function is using a repeated start sequence for writing to the
  *          specified register address.
  *
+ * @pre     i2c_acquire must be called before accessing the bus
+ *
  * @param[in]  dev          I2C peripheral device
  * @param[in]  reg          register address to read from (8- or 16-bit,
  *                          right-aligned)
-- 
GitLab