Diff: targets/TARGET_Maxim/TARGET_MAX32620C/mxc/i2cm.h

Revision:

186:707f6e361f3e

diff -r 08ed48f1de7f -r 707f6e361f3e targets/TARGET_Maxim/TARGET_MAX32620C/mxc/i2cm.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/targets/TARGET_Maxim/TARGET_MAX32620C/mxc/i2cm.h	Fri Jun 22 16:45:37 2018 +0100
@@ -0,0 +1,338 @@
+/**
+ * @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: 2017-02-16 12:08:14 -0600 (Thu, 16 Feb 2017) $
+ * $Revision: 26469 $
+ *
+ *************************************************************************** */
+
+/* Define to prevent redundant inclusion */
+#ifndef _I2CM_H_
+#define _I2CM_H_
+
+/***** Includes *****/
+#include "mxc_config.h"
+#include "mxc_sys.h"
+/**
+ * @ingroup    periphlibs
+ * @defgroup   i2cm I2C Master
+ * @brief      I2C Master Peripheral API
+ * @{
+ */
+#include "i2cm_regs.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+/* **** 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;
+
+/**
+ * @addtogroup i2cm_async
+ * @{
+ * 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. |
+ *
+ */
+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, uint8_t stop);
+
+/**
+ * @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_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);
+int I2CM_TxInProgress(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_Rx(mxc_i2cm_regs_t *i2cm, mxc_i2cm_fifo_regs_t *fifo, uint8_t addr, uint8_t *data, uint32_t len, uint8_t stop);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _I2CM_H_ */