Update modbus header file and documentation

Signed-off-by: Ajay Bhargav <[email protected]>

Author: ajaybhargav

docs/book/api/proto/modbus.rst

@@ -1,5 +1,5 @@
-Modbus Slave
-============
+Modbus Master
+=============
 
 API Reference
 -------------

include/proto/modbus.h

@@ -10,8 +10,18 @@
 
 #include <stdint.h>
 
-#define MB_BROADCAST_ADD	0
-#define MB_RESERVED_ADD		248
+/**
+ * Modbus Error codes
+ */
+enum mb_err_e {
+	MB_OK,                   /**< No error. */
+	MB_ERR_INVALID_ARG = -1, /**< Invalid argument */
+	MB_ERR_NOTSUP = 2,       /**< Mode or Function code not supported */
+	MB_ERR_TIMEOUT = -3,     /**< Modbus request timed out */
+	MB_ERR_INVALID_DATA = -4,/**< Invalid response received from slave */
+	MB_ERR_CRC_FAIL = -5,    /**< Checksum failed, CRC (for RTU) or LRC (for ASCII) */
+	MB_ERR_INIT_FAIL = -6,   /**< Fail to initialize port */
+};
 
 /**
  * MODBUS function code
@@ -55,26 +65,46 @@ enum _mb_dir {
 	MB_DIR_TX,/**< Enable write request */
 };
 
+/**
+ * Read operation structure
+ */
+struct _mb_read {
+	uint32_t start_add;	/**< Start address */
+	uint16_t no_regs;	/**< Number of registers (16-bit) to read */
+};
+
+/**
+ * Write operation structure
+ */
+struct _mb_write {
+	uint32_t wr_add;	/**< Start address */
+	uint16_t no_regs;	/**< Number of registers (16-bit) to write. For
+							 writing a 32-bit value no_regs = 2 */
+	int len;			/**< Length of data in data buffer */
+	uint8_t *data;		/**< buffer containing data to write */
+};
+
+/**
+ * Modbus operation
+ */
+union mb_op {
+	struct _mb_read read;	/**< Read operation, see @ref _mb_read */
+	struct _mb_write write;	/**< Write operation, see @ref _mb_write */
+};
+
 /**
  * MODBUS request structure
  */
 struct modbus_t {
 	uint8_t slaveid;			/**< Slave ID */
 	uint8_t function;			/**< Function code */
-	union {
-		struct _read {
-			uint32_t start_add;	/**< Start address */
-			uint16_t no_regs;	/**< Number of registers (16-bit) to read */
-		} read;					/**< Read operation structure */
-		struct _write {
-			uint32_t wr_add;	/**< Start address */
-			uint16_t no_regs;	/**< Number of registers (16-bit) to write. For writing a 32-bit value no_regs = 2 */
-			int len;			/**< Length of data in data buffer */
-			uint8_t *data;		/**< buffer containing data to write */
-		} write;				/**< Write operation structure */
-	};
-	uint8_t *resp_buf;			/**< Buffer pointer to store MODBUS response. In MODBUS ASCII mode, data will be stored after conversion from ASCII to hex */
-	uint16_t resp_buflen;		/**< Length of response buffer, On return this value will be updated with actual number of bytes stored in response buffer */
+	union mb_op op;				/**< Modbus Operation, see @ref mb_op */
+	uint8_t *resp_buf;			/**< Buffer pointer to store MODBUS response.
+									 In MODBUS ASCII mode, data will be stored
+									 after conversion from ASCII to hex */
+	uint16_t resp_buflen;		/**< Length of response buffer, On return this
+									 value will be updated with actual number of
+									 bytes stored in response buffer */
 	uint8_t resp_timeout;		/**< MODBUS response timeout in milliseconds */
 	int reserved;				/**< Reserved Unused */
 };
@@ -94,14 +124,14 @@ extern "C" {
  * @param com		[in] UART device file (e.g. /dev/ttyS1)
  * @param mode		[in] Operation mode @see _mb_mode
  * @param func		[in] Direction control callback function
- * @return			0 on success, error code otherwise
+ * @return			For return value see @ref mb_err_e
  */
 int mb_init(char *com, int mode, mb_dirctl func);
 
 /**
  * Perform a MODBUS request
  * @param mbus		[in] Modbus handle from @ref mb_init
- * @return			0 on success, error code otherwise
+ * @return			For return value see @ref mb_err_e
  */
 int mb_request(struct modbus_t *mbus);
 
@@ -125,7 +155,7 @@ unsigned char mb_lrc(unsigned char *msg, int len);
 /**
  * MODBUS exception to string
  * @param errnum	[in] Exception code
- * @return			error string (Do not free)
+ * @return			error description as string
  */
 char *mb_strerror(uint8_t errnum);