Umar Naeem
mbed library sources. Supersedes mbed-src.
Fork of
mbed-dev
by 
Umar Naeem
Diff: targets/TARGET_Maxim/TARGET_MAX32630/mxc/i2cm.h
- Revision:
- 157:ff67d9f36b67
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/targets/TARGET_Maxim/TARGET_MAX32630/mxc/i2cm.h Thu Feb 02 17:01:33 2017 +0000
@@ -0,0 +1,340 @@
+/**
+ * @file
+ * @brief I2CM (Inter-Integrated Circuit Master) function prototypes and
+ * data types.
+ */
+
+/* ****************************************************************************
+ * Copyright (C) 2016 Maxim Integrated Products, Inc., All Rights Reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
+ * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * Except as contained in this notice, the name of Maxim Integrated
+ * Products, Inc. shall not be used except as stated in the Maxim Integrated
+ * Products, Inc. Branding Policy.
+ *
+ * The mere transfer of this software does not imply any licenses
+ * of trade secrets, proprietary technology, copyrights, patents,
+ * trademarks, maskwork rights, or any other form of intellectual
+ * property whatsoever. Maxim Integrated Products, Inc. retains all
+ * ownership rights.
+ *
+ * $Date: 2016-10-10 18:58:15 -0500 (Mon, 10 Oct 2016) $
+ * $Revision: 24660 $
+ *
+ *************************************************************************** */
+
+/* Define to prevent redundant inclusion */
+#ifndef _I2CM_H_
+#define _I2CM_H_
+
+/***** Includes *****/
+#include "mxc_config.h"
+#include "mxc_sys.h"
+#include "i2cm_regs.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+/**
+ * @ingroup commperipherals
+ * @defgroup i2c_master_slave I2C
+ * @brief I2C Master and Slave Communications
+ */
+/**
+ * @ingroup i2c_master_slave
+ * @defgroup i2cm I2C Master
+ * @brief I2C Master
+ * @{
+ */
+
+/* **** Definitions **** */
+
+/**
+ * Enumeration type to select supported I2CM frequencies.
+ */
+typedef enum {
+ I2CM_SPEED_100KHZ = 0, /**< Use to select a bus communication speed of 100 kHz. */
+ I2CM_SPEED_400KHZ = 1 /**< Use to select a bus communication speed of 400 kHz. */
+} i2cm_speed_t;
+
+/**
+ * Structure type for an I2CM Transaction request.
+ */
+typedef struct i2cm_req i2cm_req_t;
+
+/**
+ * Function type for the I2C Master callback. The function declaration for the
+ * I2CM callback is:
+ * @code
+ * void callback(i2cm_req_t * req, int error_code);
+ * @endcode | | | | -----: |
+ * :----------------------------------------- | | @p req | Pointer to an
+ * #i2cm_req object representing the I2CM active transaction. | | @p error_code
+ * | An error code if the active transaction had a failure or #E_NO_ERROR if
+ * successful. |
+ *
+ * @addtogroup i2cm_async
+ * @{
+ */
+typedef void (*i2cm_callback_fn)(i2cm_req_t * req, int error_code);
+/**@}*/
+
+
+/**
+ * I2CM Transaction request structure.
+ * @note Only supports 7-bit addressing. Driver will shift the address and
+ * add the read bit when necessary.
+ */
+struct i2cm_req {
+ uint8_t addr; /**< 7-Bit unshifted address of the slave for communication. */
+ const uint8_t *cmd_data; /**< Pointer to a command data buffer to send to the slave before either a read or write transaction. */
+ uint32_t cmd_len; /**< Number of bytes in command. */
+ uint8_t *data; /**< Data to write or read. */
+ uint32_t data_len; /**< Length of data. */
+ uint32_t cmd_num; /**< Number of command bytes sent. */
+ uint32_t data_num; /**< Number of data bytes sent. */
+ i2cm_callback_fn callback; /**< Function pointer to a callback function. */
+};
+
+/* **** Globals **** */
+
+/* **** Function Prototypes **** */
+
+/**
+ * @brief Initialize the I2CM peripheral module.
+ *
+ * @param i2cm Pointer to the I2CM registers, see #mxc_i2cm_regs_t.
+ * @param sys_cfg Pointer to an I2CM configuration structure of type
+ * #sys_cfg_i2cm_t.
+ * @param speed I2CM bus speed, see #i2cm_speed_t.
+ *
+ * @return #E_NO_ERROR if initialized successfully, error if unsuccessful.
+ */
+int I2CM_Init(mxc_i2cm_regs_t *i2cm, const sys_cfg_i2cm_t *sys_cfg, i2cm_speed_t speed);
+
+/**
+ * @brief Shutdown I2CM module.
+ *
+ * @param i2cm Pointer to the I2CM registers, see #mxc_i2cm_regs_t.
+ *
+ * @returns #E_NO_ERROR if everything is successful, error if unsuccessful.
+ *
+ */
+int I2CM_Shutdown(mxc_i2cm_regs_t *i2cm);
+
+/**
+ * @defgroup i2cm_blocking I2CM Blocking Functions
+ * @{
+ */
+
+/**
+ * @brief Read I2CM data. Will block until transaction is complete.
+ *
+ * @note Command is an optional feature where the master will write the @c
+ * cmd_data before reading from the slave. If command is undesired,
+ * set the @c *cmd_data parameter to NULL and pass 0 for the @c
+ * cmd_len parameter.
+ * @note If there is a command, the master will send a repeated start
+ * sequence before attempting to read from the slave.
+ * @note This function blocks until the transaction has completed.
+ *
+ * @param i2cm Pointer to the I2CM registers, see #mxc_i2cm_regs_t.
+ * @param addr I2C address of the slave.
+ * @param cmd_data Data to write before reading.
+ * @param cmd_len Number of bytes to write before reading.
+ * @param data Where to store the data read.
+ * @param len Number of bytes to read.
+ *
+ * @return Number of bytes read if successful, error code if unsuccessful.
+ */
+int I2CM_Read(mxc_i2cm_regs_t *i2cm, uint8_t addr, const uint8_t *cmd_data,
+ uint32_t cmd_len, uint8_t* data, uint32_t len);
+
+/**
+ * @brief Write data to a slave device.
+ *
+ * @note Command is an optional feature where the master will write the @c
+ * cmd_data before writing the @c data to the slave. If command is
+ * not needed, set the @c cmd_data to @c NULL and set @c cmd_len to
+ * 0. If there is a command, the master will send a repeated start
+ * sequence before attempting to read from the slave.
+ * @note This function blocks until the transaction has completed.
+ *
+ * @param i2cm Pointer to the I2CM registers, see #mxc_i2cm_regs_t.
+ * @param addr I2C address of the slave.
+ * @param cmd_data Data to write before writing data.
+ * @param cmd_len Number of bytes to write before writing data.
+ * @param data Data to be written.
+ * @param len Number of bytes to Write.
+ *
+ * @return Number of bytes writen if successful or an @ref MXC_Error_Codes
+ * "Error Code" if unsuccessful.
+ */
+int I2CM_Write(mxc_i2cm_regs_t *i2cm, uint8_t addr, const uint8_t *cmd_data,
+ uint32_t cmd_len, uint8_t* data, uint32_t len);
+/**@} end of i2cm_blocking functions */
+
+/**
+ * @defgroup i2cm_async I2CM Asynchrous Functions
+ * @{
+ */
+
+/**
+ * @brief Asynchronously read I2CM data.
+ *
+ * @param i2cm Pointer to the I2CM registers, see #mxc_i2cm_regs_t.
+ * @param req Pointer to an I2CM transaction request structure, see
+ * #i2cm_req.
+ *
+ * @return #E_NO_ERROR if everything is successful or an @ref
+ * MXC_Error_Codes "Error Code" if unsuccessful.
+ */
+int I2CM_ReadAsync(mxc_i2cm_regs_t *i2cm, i2cm_req_t *req);
+
+/**
+ * @brief Asynchronously write I2CM data.
+ *
+ * @param i2cm Pointer to the I2CM registers, see #mxc_i2cm_regs_t.
+ * @param req Pointer to an I2CM transaction request structure, see
+ * #i2cm_req.
+ *
+ * @return #E_NO_ERROR if everything is successful, error if unsuccessful.
+ */
+int I2CM_WriteAsync(mxc_i2cm_regs_t *i2cm, i2cm_req_t *req);
+
+/**
+ * @brief Abort asynchronous request.
+ * @param req Pointer to request for an I2CM transaction.
+ * @note Will call the callback for the request.
+ *
+ * @return #E_NO_ERROR if request aborted, error if unsuccessful.
+ */
+int I2CM_AbortAsync(i2cm_req_t *req);
+
+/**
+ * @brief I2CM interrupt handler.
+ *
+ * @details This function is an IRQ handler and will be called by the core if
+ * I2CM interrupts are enabled. Alternately, if the application is
+ * using asynchronous methods, this function can be periodically
+ * called by the application if the I2CM interrupts are disabled.
+ *
+ * @param i2cm Base address of the I2CM module.
+ */
+void I2CM_Handler(mxc_i2cm_regs_t *i2cm);
+/**@} end of i2cm_async */
+
+/**
+ * @brief Returns the status of the I2CM peripheral module.
+ *
+ * @param i2cm Pointer to the I2CM register structure, see
+ * #mxc_i2cm_regs_t.
+ *
+ * @return #E_NO_ERROR if idle.
+ * @return #E_BUSY if in use.
+ */
+int I2CM_Busy(mxc_i2cm_regs_t *i2cm);
+
+/**
+ * @brief Attempt to prepare the I2CM for sleep.
+ * @details Checks for any ongoing transactions. Disables interrupts if the
+ * I2CM is idle.
+ *
+ * @param i2cm Pointer to the I2CM register structure, see
+ * #mxc_i2cm_regs_t.
+ *
+ * @return #E_NO_ERROR if ready to sleep.
+ * @return #E_BUSY if the bus is not ready for sleep.
+ */
+int I2CM_PrepForSleep(mxc_i2cm_regs_t *i2cm);
+
+/**
+ * @brief Check the I2C bus to determine if any other masters are using the
+ * bus.
+ *
+ * @param i2cm Pointer to the I2CM register structure, see
+ * #mxc_i2cm_regs_t.
+ *
+ * @return #E_NO_ERROR if SCL and SDA are high,
+ * @return #E_BUSY otherwise.
+ */
+int I2CM_BusCheck(mxc_i2cm_regs_t *i2cm);
+
+/**
+ * @brief Drain/Empty all of the data in the I2CM Receive FIFO.
+ *
+ * @param i2cm Pointer to the I2CM register structure, see
+ * #mxc_i2cm_regs_t.
+ */
+__STATIC_INLINE void I2CM_DrainRX(mxc_i2cm_regs_t *i2cm)
+{
+ i2cm->ctrl &= ~(MXC_F_I2CM_CTRL_RX_FIFO_EN);
+ i2cm->ctrl |= MXC_F_I2CM_CTRL_RX_FIFO_EN;
+}
+
+/**
+ * @brief Drain/Empty any data in the I2CM Transmit FIFO.
+ *
+ * @param i2cm Pointer to the I2CM register structure, see
+ * #mxc_i2cm_regs_t.
+ */
+__STATIC_INLINE void I2CM_DrainTX(mxc_i2cm_regs_t *i2cm)
+{
+ i2cm->ctrl &= ~(MXC_F_I2CM_CTRL_TX_FIFO_EN);
+ i2cm->ctrl |= MXC_F_I2CM_CTRL_TX_FIFO_EN;
+}
+
+/**
+ * @brief Clear interrupt flags.
+ *
+ * @param i2cm Pointer to the I2CM register structure, see
+ * #mxc_i2cm_regs_t.
+ * @param mask Mask of I2CM interrupts to clear (1 to clear),
+ * @see I2CM_INTFL_Register for the interrupt flag masks.
+ */
+__STATIC_INLINE void I2CM_ClearFlags(mxc_i2cm_regs_t *i2cm, uint32_t mask)
+{
+ i2cm->intfl = mask;
+}
+
+/**
+ * @brief Gets the current I2CM interrupt flags.
+ * @param i2cm Pointer to the I2CM register structure, see
+ * #mxc_i2cm_regs_t.
+ *
+ * @return The currently set interrupt flags, @see I2CM_INTFL_Register
+ * for the interrupt flag masks.
+ */
+__STATIC_INLINE unsigned I2CM_GetFlags(mxc_i2cm_regs_t *i2cm)
+{
+ return(i2cm->intfl);
+}
+/**@} end of group i2cm */
+
+void I2CM_Recover(mxc_i2cm_regs_t *i2cm);
+int I2CM_WriteTxFifo(mxc_i2cm_regs_t *regs, mxc_i2cm_fifo_regs_t *fifo, const uint16_t data);
+int I2CM_TxInProgress(mxc_i2cm_regs_t *i2cm);
+int I2CM_Tx(mxc_i2cm_regs_t *i2cm, mxc_i2cm_fifo_regs_t *fifo, uint8_t addr, const uint8_t *data, uint32_t len, uint8_t stop);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _I2CM_H_ */