changes to support APi review by Greg. Also changed the start/stop API
to begin/end to differentiate from the i2c bus start/stop conditions
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/commit/0892fd98
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/tree/0892fd98
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/diff/0892fd98
Branch: refs/heads/master
Commit: 0892fd98e40a9cdf295fa99b1041822cc9a89519
Parents: 4d0a387
Author: Paul Dietrich <pa...@yahoo.com>
Authored: Thu Apr 21 10:30:31 2016 -0700
Committer: Paul Dietrich <pa...@yahoo.com>
Committed: Thu Apr 21 10:32:32 2016 -0700
----------------------------------------------------------------------
hw/hal/include/hal/hal_i2c.h | 86 ++++++++++++++++++++++++++-------------
hw/hal/src/hal_i2c.c | 5 +--
2 files changed, 59 insertions(+), 32 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/0892fd98/hw/hal/include/hal/hal_i2c.h
----------------------------------------------------------------------
diff --git a/hw/hal/include/hal/hal_i2c.h b/hw/hal/include/hal/hal_i2c.h
index 82546d4..20b697d 100644
--- a/hw/hal/include/hal/hal_i2c.h
+++ b/hw/hal/include/hal/hal_i2c.h
@@ -20,64 +20,92 @@
#ifndef HAL_I2C_H
#define HAL_I2C_H
+#include <inttypes.h>
+#include <bsp/bsp_sysid.h>
+
#ifdef __cplusplus
extern "C" {
#endif
-#include <inttypes.h>
-#include <bsp/bsp_sysid.h>
-
-/* This is the API for an i2c bus. I tried to make this a simple API */
+/* This is the API for an i2c bus. Currently, this is a master API
+ * allowing the mynewt device to function as an I2C master.
+ *
+ * A slave API is pending for future release
+ *
+ * Typical usage of this API is as follows:
+ *
+ * Initialize an i2c device with
+ * hal_i2c_init()
+ *
+ * When you with to perform an i2c transaction, issue
+ * hal_i2c_master_begin()l
+ * followed by the transaction. For example, in an I2C memory access access
+ * you might write and address and then read back data
+ * hal_i2c_write(); -- write amemory ddress to device
+ * hal_i2c_read(); --- read back data
+ * then end the transaction
+ * hal_i2c_end();
+ */
struct hal_i2c;
/* when sending a packet, use this structure to pass the arguments */
struct hal_i2c_master_data {
uint8_t address; /* destination address */
- /* NOTE: Write addresses are even and read addresses are odd
- * but in this API, you must enter a single address that is the
- * write address divide by 2. For example, for address
- * 80, you would enter a 40 */
+ /* a I2C address has 7 bits. In the protocol these
+ * 7 bits are combined with a 1 bit R/W bit to specify read
+ * or write operation in an 8-bit address field sent to
+ * the remote device . This API accepts the 7-bit
+ * address as its argument in the 7 LSBs of the
+ * address field above. For example if I2C was
+ * writing a 0x81 in its protocol, you would pass
+ * only the top 7-bits to this function as 0x40 */
+ uint16_t len; /* number of buffer bytes to transmit or receive */
uint8_t *buffer; /* buffer space to hold the transmit or receive */
- uint16_t len; /* length of buffer to transmit or receive */
};
/* Initialize a new i2c device with the given system id.
- * Returns negative on error, 0 on success. */
+ * Returns a pointer to the i2c device or NULL on error */
struct hal_i2c*
hal_i2c_init(enum system_device_id sysid);
-/* Sends <len> bytes of data on the i2c. This API assumes that you
- * issued a successful start condition. It will fail if you
- * have not. This API does NOT issue a stop condition. You must stop the
- * bus after successful or unsuccessful write attempts. Returns 0 on
- * success, negative on failure */
+/* Sends a start condition and writes <len> bytes of data on the i2c.
+ * This API assumes that you have already called hal_i2c_master_begin
+ * It will fail if you have not. This API does NOT issue a stop condition.
+ * You must stop the bus after successful or unsuccessful write attempts.
+ * This API is blocking until an error or NaK occurs. Timeout is platform
+ * dependent
+ * Returns 0 on success, negative on failure */
int
hal_i2c_master_write(struct hal_i2c*, struct hal_i2c_master_data *pdata);
-/* Reads <len> bytes of data on the i2c. This API assumes that you
- * issued a successful start condition. It will fail if you
- * have not. This API does NOT issue a stop condition. You must stop the
- * bus after successful or unsuccessful write attempts. Returns 0 on
- * success, negative on failure */
+/* Sends a start condition and reads <len> bytes of data on the i2c.
+ * This API assumes that you have already called hal_i2c_master_begin
+ * It will fail if you have not. This API does NOT issue a stop condition.
+ * You must stop the bus after successful or unsuccessful write attempts.
+ * This API is blocking until an error or NaK occurs. Timeout is platform
+ * dependent
+ * Returns 0 on success, negative on failure */
int
hal_i2c_master_read(struct hal_i2c*, struct hal_i2c_master_data *pdata);
-/* issues a start condition and address on the SPI bus. Returns 0
- * on success, negative on error.
+/*
+ * Starts an I2C transaction with the driver. This API does not send
+ * anything over the bus itself
*/
int
-hal_i2c_master_start(struct hal_i2c*);
+hal_i2c_master_begin(struct hal_i2c*);
-/* issues a stop condition on the bus. You must issue a stop condition for
- * every successful start condition on the bus */
+/* issues a stop condition on the bus and ends the I2C transaction.
+ * You must call i2c_master_end for every hal_i2c_master_begin
+ * API call that succeeds */
int
-hal_i2c_master_stop(struct hal_i2c*);
-
+hal_i2c_master_end(struct hal_i2c*);
/* Probes the i2c bus for a device with this address. THIS API
- * issues a start condition, probes the address and issues a stop
- * condition.
+ * issues a start condition, probes the address using a read
+ * command and issues a stop condition. There is no need to call
+ * hal_i2c_master_begin/end with this method
*/
int
hal_i2c_master_probe(struct hal_i2c*, uint8_t address);
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/0892fd98/hw/hal/src/hal_i2c.c
----------------------------------------------------------------------
diff --git a/hw/hal/src/hal_i2c.c b/hw/hal/src/hal_i2c.c
index bd20620..c383fe5 100644
--- a/hw/hal/src/hal_i2c.c
+++ b/hw/hal/src/hal_i2c.c
@@ -57,7 +57,7 @@ hal_i2c_master_probe(struct hal_i2c *pi2c, uint8_t address)
}
int
-hal_i2c_master_start(struct hal_i2c *pi2c)
+hal_i2c_master_begin(struct hal_i2c *pi2c)
{
if (pi2c && pi2c->driver_api && pi2c->driver_api->hi2cm_start )
{
@@ -66,9 +66,8 @@ hal_i2c_master_start(struct hal_i2c *pi2c)
return -1;
}
-
int
-hal_i2c_master_stop(struct hal_i2c *pi2c)
+hal_i2c_master_end(struct hal_i2c *pi2c)
{
if (pi2c && pi2c->driver_api && pi2c->driver_api->hi2cm_stop )
{