You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by we...@apache.org on 2016/11/09 18:51:36 UTC
incubator-mynewt-core git commit: Modify comments for hal_i2c.h to
match current API.
Repository: incubator-mynewt-core
Updated Branches:
refs/heads/develop c61985b33 -> 83129d438
Modify comments for hal_i2c.h to match current API.
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/83129d43
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/tree/83129d43
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/diff/83129d43
Branch: refs/heads/develop
Commit: 83129d438fb4c5419db150b8eb690d5659e4cf6f
Parents: c61985b
Author: William San Filippo <wi...@runtime.io>
Authored: Wed Nov 9 10:51:04 2016 -0800
Committer: William San Filippo <wi...@runtime.io>
Committed: Wed Nov 9 10:51:04 2016 -0800
----------------------------------------------------------------------
hw/hal/include/hal/hal_i2c.h | 41 ++++++++++++++++++++++-----------------
1 file changed, 23 insertions(+), 18 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/83129d43/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 b244c01..9e8d8d9 100644
--- a/hw/hal/include/hal/hal_i2c.h
+++ b/hw/hal/include/hal/hal_i2c.h
@@ -34,17 +34,24 @@ extern "C" {
*
* Typical usage of this API is as follows:
*
- * Initialize an i2c device with
+ * 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();
+ * When you wish to perform an i2c transaction, you call one or both of:
+ * hal_i2c_master_write();
+ * hal_i2c_master_read();
+ *
+ * These functions will issue a START condition, followed by the device's
+ * 7-bit I2C address, and then send or receive the payload based on the data
+ * provided. This will cause a repeated start on the bus, which is valid in
+ * I2C specification, and the decision to use repeated starts was made to
+ * simplify the I2C HAL. To set the STOP condition at an appropriate moment,
+ * you set the `last_op` field to a `1` in either function.
+ *
+ * For example, in an I2C memory access you might write a register address and
+ * then read data back via:
+ * hal_i2c_write(); -- write to a specific register on the device
+ * hal_i2c_read(); --- read back data, setting 'last_op' to '1'
*/
/**
@@ -52,10 +59,10 @@ extern "C" {
*/
struct hal_i2c_master_data {
uint8_t address; /* destination address */
- /* a I2C address has 7 bits. In the protocol these
+ /* An 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
+ * 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
@@ -76,9 +83,8 @@ struct hal_i2c_master_data {
int hal_i2c_init(uint8_t i2c_num, void *cfg);
/**
- * 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.
+ * Sends a start condition and writes <len> bytes of data on the i2c bus.
+ * This API does NOT issue a stop condition unless `last_op` is set to `1`.
* 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.
@@ -95,9 +101,8 @@ int hal_i2c_master_write(uint8_t i2c_num, struct hal_i2c_master_data *pdata,
uint32_t timeout, uint8_t last_op);
/**
- * 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.
+ * Sends a start condition and reads <len> bytes of data on the i2c bus.
+ * This API does NOT issue a stop condition unless `last_op` is set to `1`.
* 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.
@@ -116,7 +121,7 @@ int hal_i2c_master_read(uint8_t i2c_num, struct hal_i2c_master_data *pdata,
/**
* Probes the i2c bus for a device with this address. THIS API
* issues a start condition, probes the address using a read
- * command and issues a stop condition. There is no need to call
+ * command and issues a stop condition.
* hal_i2c_master_begin/end with this method.
*
* @param i2c_num The number of the I2C to probe