i2c: add doxygen documentation and make return types use maa_result_t

Signed-off-by: Brendan Le Foll <brendan.le.foll@intel.com>

api/i2c.h

@@ -35,11 +35,16 @@ extern "C" {
 #include "maa.h"
 #include "gpio.h"
 
+/**
+ * A structure representing an i2c device /dev/i2c-*
+ */
 typedef struct {
-    int hz;
+    /*@{*/
-    int fh;
+    int hz; /**< frequency of communication */
-    int addr;
+    int fh; /**< the file handle to the /dev/i2c-* device */
+    int addr; /**< the address of the i2c slave */
     maa_gpio_context gpio;
+    /*@}*/
 } maa_i2c_context;
 
 maa_i2c_context* maa_i2c_init();
@@ -48,20 +53,18 @@ maa_i2c_context* maa_i2c_init();
  *
  *  @param dev the i2c context
  *  @param hz The bus frequency in hertz
+ *
+ *  @return maa_result_t the maa result.
  */
-void maa_i2c_frequency(maa_i2c_context* dev, int hz);
+maa_result_t maa_i2c_frequency(maa_i2c_context* dev, int hz);
 
 /** Checks to see if this I2C Slave has been addressed.
  *
  *  @param dev the i2c context
- *  @returns
+ *
- *  A status indicating if the device has been addressed, and how
+ *  @return maa_result_t the maa result.
- *  - NoData            - the slave has not been addressed
- *  - ReadAddressed     - the master has requested a read from this slave
- *  - WriteAddressed    - the master is writing to this slave
- *  - WriteGeneral      - the master is writing to all slave
  */
-int maa_i2c_receive(maa_i2c_context* dev);
+maa_result_t maa_i2c_receive(maa_i2c_context* dev);
 
 /** Read from an I2C master.
  *
@@ -69,17 +72,15 @@ int maa_i2c_receive(maa_i2c_context* dev);
  *  @param data pointer to the byte array to read data in to
  *  @param length maximum number of bytes to read
  *
- *  @returns
+ *  @return maa_result_t the maa result.
- *       0 on success,
- *   non-0 otherwise
  */
-int maa_i2c_read(maa_i2c_context* dev, char *data, int length);
+maa_result_t maa_i2c_read(maa_i2c_context* dev, char *data, int length);
 
 /** Read a single byte from an I2C master.
  *
  *  @param dev the i2c context
- *  @returns
+ *
- *    the byte read
+ *  @return byte the result of the read or -1 if failed.
  */
 int maa_i2c_read_byte(maa_i2c_context* dev);
 
@@ -89,22 +90,18 @@ int maa_i2c_read_byte(maa_i2c_context* dev);
  *  @param data pointer to the byte array to be transmitted
  *  @param length the number of bytes to transmite
  *
- *  @returns
+ *  @return maa_result_t the maa result.
- *       0 on success,
- *   non-0 otherwise
  */
-int maa_i2c_write(maa_i2c_context* dev, const char *data, int length);
+maa_result_t maa_i2c_write(maa_i2c_context* dev, const char *data, int length);
 
 /** Write a single byte to an I2C master.
  *
  *  @param dev the i2c context
  *  @data the byte to write
  *
- *  @returns
+ *  @return maa_result_t the maa result.
- *    '1' if an ACK was received,
- *    '0' otherwise
  */
-int maa_i2c_write_byte(maa_i2c_context* dev, int data);
+maa_result_t maa_i2c_write_byte(maa_i2c_context* dev, int data);
 
 /** Sets the I2C slave address.
  *
@@ -112,14 +109,18 @@ int maa_i2c_write_byte(maa_i2c_context* dev, int data);
  *  @param address The address to set for the slave (ignoring the least
  *  signifcant bit). If set to 0, the slave will only respond to the
  *  general call address.
+ *
+ *  @return maa_result_t the maa result.
  */
-void maa_i2c_address(maa_i2c_context* dev, int address);
+maa_result_t maa_i2c_address(maa_i2c_context* dev, int address);
 
 /** De-inits an maa_i2c_context device
  *
  *  @param dev the i2c context
+ *
+ *  @return maa_result_t the maa result.
  */
-void maa_i2c_stop(maa_i2c_context* dev);
+maa_result_t maa_i2c_stop(maa_i2c_context* dev);
 
 #ifdef __cplusplus
 }

src/i2c/i2c.c

@@ -40,26 +40,28 @@ maa_i2c_init()
     return dev;
 }
 
-void
+maa_result_t
 maa_i2c_frequency(maa_i2c_context* dev, int hz)
 {
     dev->hz = hz;
+
+    return MAA_SUCCESS;
 }
 
-int
+maa_result_t
 maa_i2c_receive(maa_i2c_context* dev)
 {
-    return -1;
+    return MAA_ERROR_FEATURE_NOT_IMPLEMENTED;
 }
 
-int
+maa_result_t
 maa_i2c_read(maa_i2c_context* dev, char *data, int length)
 {
     // this is the read(3) syscall not maa_i2c_read()
     if (read(dev->fh, data, length) == length) {
         return length;
     }
-    return -1;
+    return MAA_ERROR_NO_DATA_AVAILABLE;
 }
 
 int
@@ -73,37 +75,40 @@ maa_i2c_read_byte(maa_i2c_context* dev)
     return byte;
 }
 
-int
+maa_result_t
 maa_i2c_write(maa_i2c_context* dev, const char* data, int length)
 {
     if (i2c_smbus_write_i2c_block_data(dev->fh, data[0], length-1, (uint8_t*) data+1) < 0) {
-        fprintf(stderr, "Failed to write to I2CSlave slave\n");
+        fprintf(stderr, "Failed to write to i2c\n");
-	return -1;
+	return MAA_ERROR_INVALID_HANDLE;
     }
-    return 0;
+    return MAA_SUCCESS;
 }
 
-int
+maa_result_t
 maa_i2c_write_byte(maa_i2c_context* dev, int data)
 {
     if (i2c_smbus_write_byte(dev->fh, data) < 0) {
-        fprintf(stderr, "Failed to write to I2CSlave slave\n");
+        fprintf(stderr, "Failed to write to i2c\n");
-	return -1;
+	return MAA_ERROR_INVALID_HANDLE;
     }
-    return 0;
+    return MAA_SUCCESS;
 }
 
-void
+maa_result_t
 maa_i2c_address(maa_i2c_context* dev, int addr)
 {
     dev->addr = addr;
     if (ioctl(dev->fh, I2C_SLAVE_FORCE, addr) < 0) {
         fprintf(stderr, "Failed to set slave address %d\n", addr);
+	return MAA_ERROR_INVALID_HANDLE;
     }
+    return MAA_SUCCESS;
 }
 
-void
+maa_result_t
 maa_i2c_stop(maa_i2c_context* dev)
 {
     free(dev);
+    return MAA_SUCCESS;
 }