m2m_periph.h

00001 /**
00002  *
00003  * \file
00004  *
00005  * \brief WINC Peripherals Application Interface.
00006  *
00007  * Copyright (c) 2016 Atmel Corporation. All rights reserved.
00008  *
00009  * \asf_license_start
00010  *
00011  * \page License
00012  *
00013  * Redistribution and use in source and binary forms, with or without
00014  * modification, are permitted provided that the following conditions are met:
00015  *
00016  * 1. Redistributions of source code must retain the above copyright notice,
00017  *    this list of conditions and the following disclaimer.
00018  *
00019  * 2. Redistributions in binary form must reproduce the above copyright notice,
00020  *    this list of conditions and the following disclaimer in the documentation
00021  *    and/or other materials provided with the distribution.
00022  *
00023  * 3. The name of Atmel may not be used to endorse or promote products derived
00024  *    from this software without specific prior written permission.
00025  *
00026  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
00027  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00028  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
00029  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
00030  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00031  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00032  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00033  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
00034  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00035  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00036  * POSSIBILITY OF SUCH DAMAGE.
00037  *
00038  * \asf_license_stop
00039  *
00040  */
00041 
00042 #ifndef _M2M_PERIPH_H_
00043 #define _M2M_PERIPH_H_
00044 
00045 
00046 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
00047 INCLUDES
00048 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
00049 
00050 
00051 #include "common/include/nm_common.h"
00052 #include "driver/include/m2m_types.h"
00053 
00054 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
00055 MACROS
00056 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
00057 
00058 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
00059 DATA TYPES
00060 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
00061 
00062 /*!
00063 @struct \
00064     tstrPerphInitParam
00065 
00066 @brief
00067     Peripheral module initialization parameters.
00068 */
00069 typedef struct {
00070     void * arg;
00071 } tstrPerphInitParam;
00072 
00073 
00074 /*!
00075 @enum   \
00076     tenuGpioNum
00077 
00078 @brief
00079     A list of GPIO numbers configurable through the m2m_periph module.
00080 */
00081 typedef enum {
00082     M2M_PERIPH_GPIO3 , /*!< GPIO15 pad   */
00083     M2M_PERIPH_GPIO4 , /*!< GPIO16 pad   */
00084     M2M_PERIPH_GPIO5 , /*!< GPIO18 pad   */
00085     M2M_PERIPH_GPIO6 , /*!< GPIO18 pad   */
00086     M2M_PERIPH_GPIO15 , /*!< GPIO15 pad  */
00087     M2M_PERIPH_GPIO16 , /*!< GPIO16 pad  */
00088     M2M_PERIPH_GPIO18 , /*!< GPIO18 pad  */
00089     M2M_PERIPH_GPIO_MAX
00090 } tenuGpioNum;
00091 
00092 
00093 /*!
00094 @enum   \
00095     tenuI2cMasterSclMuxOpt
00096 
00097 @brief
00098     Allowed pin multiplexing options for I2C master SCL signal.
00099 */
00100 typedef enum {
00101     M2M_PERIPH_I2C_MASTER_SCL_MUX_OPT_HOST_WAKEUP , /*!< I2C master SCL is avaiable on HOST_WAKEUP. */
00102     M2M_PERIPH_I2C_MASTER_SCL_MUX_OPT_SD_DAT3 ,     /*!< I2C master SCL is avaiable on SD_DAT3 (GPIO 7). */
00103     M2M_PERIPH_I2C_MASTER_SCL_MUX_OPT_GPIO13 ,      /*!< I2C master SCL is avaiable on GPIO 13. */
00104     M2M_PERIPH_I2C_MASTER_SCL_MUX_OPT_GPIO4 ,       /*!< I2C master SCL is avaiable on GPIO 4.*/
00105     M2M_PERIPH_I2C_MASTER_SCL_MUX_OPT_I2C_SCL ,     /*!< I2C master SCL is avaiable on I2C slave SCL. */
00106     M2M_PERIPH_I2C_MASTER_SCL_MUX_OPT_NUM
00107 } tenuI2cMasterSclMuxOpt;
00108 
00109 /*!
00110 @enum   \
00111     tenuI2cMasterSdaMuxOpt
00112 
00113 @brief
00114     Allowed pin multiplexing options for I2C master SDA signal.
00115 */
00116 typedef enum {
00117     M2M_PERIPH_I2C_MASTER_SDA_MUX_OPT_RTC_CLK  , /*!< I2C master SDA is avaiable on RTC_CLK. */
00118     M2M_PERIPH_I2C_MASTER_SDA_MUX_OPT_SD_CLK ,   /*!< I2C master SDA is avaiable on SD_CLK (GPIO 8). */
00119     M2M_PERIPH_I2C_MASTER_SDA_MUX_OPT_GPIO14 ,   /*!< I2C master SDA is avaiable on GPIO 14. */
00120     M2M_PERIPH_I2C_MASTER_SDA_MUX_OPT_GPIO6 ,    /*!< I2C master SDA is avaiable on GPIO 6.*/
00121     M2M_PERIPH_I2C_MASTER_SDA_MUX_OPT_I2C_SDA ,  /*!< I2C master SDA is avaiable on I2C slave SDA. */
00122     M2M_PERIPH_I2C_MASTER_SDA_MUX_OPT_NUM
00123 } tenuI2cMasterSdaMuxOpt;
00124 
00125 
00126 /*!
00127 @struct \
00128     tstrI2cMasterInitParam
00129 
00130 @brief
00131     I2C master configuration parameters.
00132 @sa
00133     tenuI2cMasterSclMuxOpt
00134     tenuI2cMasterSdaMuxOpt
00135 */
00136 typedef struct {
00137     uint8 enuSclMuxOpt ; /*!< SCL multiplexing option. Allowed value are defined in tenuI2cMasterSclMuxOpt  */
00138     uint8 enuSdaMuxOpt ; /*!< SDA multiplexing option. Allowed value are defined in tenuI2cMasterSdaMuxOpt  */
00139     uint8 u8ClkSpeedKHz ; /*!< I2C master clock speed in KHz. */
00140 } tstrI2cMasterInitParam;
00141 
00142 /*!
00143 @enum   \
00144     tenuI2cMasterFlags
00145 
00146 @brief
00147     Bitwise-ORed flags for use in m2m_periph_i2c_master_write and m2m_periph_i2c_master_read
00148 @sa
00149     m2m_periph_i2c_master_write
00150     m2m_periph_i2c_master_read
00151 */
00152 typedef enum  {
00153     I2C_MASTER_NO_FLAGS           = 0x00,
00154     /*!< No flags.  */
00155     I2C_MASTER_NO_STOP            = 0x01,
00156     /*!< No stop bit after this transaction. Useful for scattered buffer read/write operations. */
00157     I2C_MASTER_NO_START           = 0x02,
00158     /*!< No start bit at the beginning of this transaction. Useful for scattered buffer read/write operations.*/
00159 } tenuI2cMasterFlags;
00160 
00161 /*!
00162 @enum   \
00163     tenuPullupMask
00164 
00165 @brief
00166     Bitwise-ORed flags for use in m2m_perph_pullup_ctrl.
00167 @sa
00168     m2m_periph_pullup_ctrl
00169 
00170 */
00171 typedef enum {
00172     M2M_PERIPH_PULLUP_DIS_HOST_WAKEUP     = (1ul << 0),
00173     M2M_PERIPH_PULLUP_DIS_RTC_CLK         = (1ul << 1),
00174     M2M_PERIPH_PULLUP_DIS_IRQN            = (1ul << 2),
00175     M2M_PERIPH_PULLUP_DIS_GPIO_3          = (1ul << 3),
00176     M2M_PERIPH_PULLUP_DIS_GPIO_4          = (1ul << 4),
00177     M2M_PERIPH_PULLUP_DIS_GPIO_5          = (1ul << 5),
00178     M2M_PERIPH_PULLUP_DIS_SD_DAT3         = (1ul << 6),
00179     M2M_PERIPH_PULLUP_DIS_SD_DAT2_SPI_RXD = (1ul << 7),
00180     M2M_PERIPH_PULLUP_DIS_SD_DAT1_SPI_SSN = (1ul << 9),
00181     M2M_PERIPH_PULLUP_DIS_SD_CMD_SPI_SCK  = (1ul << 10),
00182     M2M_PERIPH_PULLUP_DIS_SD_DAT0_SPI_TXD = (1ul << 11),
00183     M2M_PERIPH_PULLUP_DIS_GPIO_6          = (1ul << 12),
00184     M2M_PERIPH_PULLUP_DIS_SD_CLK          = (1ul << 13),
00185     M2M_PERIPH_PULLUP_DIS_I2C_SCL         = (1ul << 14),
00186     M2M_PERIPH_PULLUP_DIS_I2C_SDA         = (1ul << 15),
00187     M2M_PERIPH_PULLUP_DIS_GPIO_11         = (1ul << 16),
00188     M2M_PERIPH_PULLUP_DIS_GPIO_12         = (1ul << 17),
00189     M2M_PERIPH_PULLUP_DIS_GPIO_13         = (1ul << 18),
00190     M2M_PERIPH_PULLUP_DIS_GPIO_14         = (1ul << 19),
00191     M2M_PERIPH_PULLUP_DIS_GPIO_15         = (1ul << 20),
00192     M2M_PERIPH_PULLUP_DIS_GPIO_16         = (1ul << 21),
00193     M2M_PERIPH_PULLUP_DIS_GPIO_17         = (1ul << 22),
00194     M2M_PERIPH_PULLUP_DIS_GPIO_18         = (1ul << 23),
00195     M2M_PERIPH_PULLUP_DIS_GPIO_19         = (1ul << 24),
00196     M2M_PERIPH_PULLUP_DIS_GPIO_20         = (1ul << 25),
00197     M2M_PERIPH_PULLUP_DIS_GPIO_21         = (1ul << 26),
00198     M2M_PERIPH_PULLUP_DIS_GPIO_22         = (1ul << 27),
00199     M2M_PERIPH_PULLUP_DIS_GPIO_23         = (1ul << 28),
00200     M2M_PERIPH_PULLUP_DIS_GPIO_24         = (1ul << 29),
00201 } tenuPullupMask;
00202 
00203 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
00204 FUNCTION PROTOTYPES
00205 *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
00206 
00207 
00208 #ifdef __cplusplus
00209      extern "C" {
00210 #endif
00211 
00212 /*!
00213 @fn \
00214     NMI_API sint8 m2m_periph_init(tstrPerphInitParam * param);
00215 
00216 @brief
00217     Initialize the NMC1500 peripheral driver module.
00218 
00219 @param [in] param
00220                 Peripheral module initialization structure. See members of tstrPerphInitParam.
00221 
00222 @return
00223     The function SHALL return 0 for success and a negative value otherwise.
00224 
00225 @sa
00226     tstrPerphInitParam
00227 */
00228 NMI_API sint8 m2m_periph_init(tstrPerphInitParam * param);
00229 
00230 /*!
00231 @fn \
00232     NMI_API sint8 m2m_periph_gpio_set_dir(uint8 u8GpioNum, uint8 u8GpioDir);
00233 
00234 @brief
00235     Configure a specific NMC1500 pad as a GPIO and sets its direction (input or output).
00236 
00237 @param [in] u8GpioNum
00238                 GPIO number. Allowed values are defined in tenuGpioNum.
00239 
00240 @param [in] u8GpioDir
00241                 GPIO direction: Zero = input. Non-zero = output.
00242 
00243 @return
00244     The function SHALL return 0 for success and a negative value otherwise.
00245 
00246 @sa
00247     tenuGpioNum
00248 */
00249 NMI_API sint8 m2m_periph_gpio_set_dir(uint8 u8GpioNum, uint8 u8GpioDir);
00250 
00251 /*!
00252 @fn \
00253     NMI_API sint8 m2m_periph_gpio_set_val(uint8 u8GpioNum, uint8 u8GpioVal);
00254 
00255 @brief
00256     Set an NMC1500 GPIO output level high or low.
00257 
00258 @param [in] u8GpioNum
00259                 GPIO number. Allowed values are defined in tenuGpioNum.
00260 
00261 @param [in] u8GpioVal
00262                 GPIO output value. Zero = low, non-zero = high.
00263 
00264 @return
00265     The function SHALL return 0 for success and a negative value otherwise.
00266 
00267 @sa
00268     tenuGpioNum
00269 */
00270 NMI_API sint8 m2m_periph_gpio_set_val(uint8 u8GpioNum, uint8 u8GpioVal);
00271 
00272 /*!
00273 @fn \
00274     NMI_API sint8 m2m_periph_gpio_get_val(uint8 u8GpioNum, uint8 * pu8GpioVal);
00275 
00276 @brief
00277     Read an NMC1500 GPIO input level.
00278 
00279 @param [in] u8GpioNum
00280                 GPIO number. Allowed values are defined in tenuGpioNum.
00281 
00282 @param [out] pu8GpioVal
00283                 GPIO input value. Zero = low, non-zero = high.
00284 
00285 @return
00286     The function SHALL return 0 for success and a negative value otherwise.
00287 
00288 @sa
00289     tenuGpioNum
00290 */
00291 NMI_API sint8 m2m_periph_gpio_get_val(uint8 u8GpioNum, uint8 * pu8GpioVal);
00292 
00293 /*!
00294 @fn \
00295     NMI_API sint8 m2m_periph_gpio_pullup_ctrl(uint8 u8GpioNum, uint8 u8PullupEn);
00296 
00297 @brief
00298     Set an NMC1500 GPIO pullup resisitor enable or disable.
00299 
00300 @param [in] u8GpioNum
00301                 GPIO number. Allowed values are defined in tenuGpioNum.
00302 
00303 @param [in] u8PullupEn
00304                 Zero: pullup disabled. Non-zero: pullup enabled.
00305 
00306 @return
00307     The function SHALL return 0 for success and a negative value otherwise.
00308 
00309 @sa
00310     tenuGpioNum
00311 */
00312 NMI_API sint8 m2m_periph_gpio_pullup_ctrl(uint8 u8GpioNum, uint8 u8PullupEn);
00313 
00314 /*!
00315 @fn \
00316     NMI_API sint8 m2m_periph_i2c_master_init(tstrI2cMasterInitParam * param);
00317 
00318 @brief
00319     Initialize and configure the NMC1500 I2C master peripheral.
00320 
00321 @param [in] param
00322                 I2C master initialization structure. See members of tstrI2cMasterInitParam.
00323 
00324 @return
00325     The function SHALL return 0 for success and a negative value otherwise.
00326 
00327 @sa
00328     tstrI2cMasterInitParam
00329 */
00330 NMI_API sint8 m2m_periph_i2c_master_init(tstrI2cMasterInitParam * param);
00331 
00332 /*!
00333 @fn \
00334     NMI_API sint8 m2m_periph_i2c_master_write(uint8 u8SlaveAddr, uint8 * pu8Buf, uint16 u16BufLen, uint8 flags);
00335 
00336 @brief
00337     Write a stream of bytes to the I2C slave device.
00338 
00339 @param [in] u8SlaveAddr
00340                 7-bit I2C slave address.
00341 @param [in] pu8Buf
00342                 A pointer to an input buffer which contains a stream of bytes.
00343 @param [in] u16BufLen
00344                 Input buffer length in bytes.
00345 @param [in] flags
00346                 Write operation bitwise-ORed flags. See tenuI2cMasterFlags.
00347 
00348 @return
00349     The function SHALL return 0 for success and a negative value otherwise.
00350 
00351 @sa
00352     tenuI2cMasterFlags
00353 */
00354 NMI_API sint8 m2m_periph_i2c_master_write(uint8 u8SlaveAddr, uint8 * pu8Buf, uint16 u16BufLen, uint8 flags);
00355 
00356 
00357 /*!
00358 @fn \
00359     NMI_API sint8 m2m_periph_i2c_master_read(uint8 u8SlaveAddr, uint8 * pu8Buf, uint16 u16BufLen, uint16 * pu16ReadLen, uint8 flags);
00360 
00361 @brief
00362     Write a stream of bytes to the I2C slave device.
00363 
00364 @param [in] u8SlaveAddr
00365                 7-bit I2C slave address.
00366 @param [out] pu8Buf
00367                 A pointer to an output buffer in which a stream of bytes are received.
00368 @param [in] u16BufLen
00369                 Max output buffer length in bytes.
00370 @param [out] pu16ReadLen
00371                 Actual number of bytes received.
00372 @param [in] flags
00373                 Write operation bitwise-ORed flags. See tenuI2cMasterFlags.
00374 
00375 @return
00376     The function SHALL return 0 for success and a negative value otherwise.
00377 
00378 @sa
00379     tenuI2cMasterFlags
00380 */
00381 NMI_API sint8 m2m_periph_i2c_master_read(uint8 u8SlaveAddr, uint8 * pu8Buf, uint16 u16BufLen, uint16 * pu16ReadLen, uint8 flags);
00382 
00383 
00384 /*!
00385 @fn \
00386     NMI_API sint8 m2m_periph_pullup_ctrl(uint32 pinmask, uint8 enable);
00387 
00388 @brief
00389     Control the programmable pull-up resistor on the chip pads .
00390 
00391 
00392 @param [in] pinmask
00393                 Write operation bitwise-ORed mask for which pads to control. Allowed values are defined in tenuPullupMask.
00394 
00395 @param [in] enable
00396                 Set to 0 to disable pull-up resistor. Non-zero will enable the pull-up.
00397 
00398 @return
00399     The function SHALL return 0 for success and a negative value otherwise.
00400 
00401 @sa
00402     tenuPullupMask
00403 */
00404 NMI_API sint8 m2m_periph_pullup_ctrl(uint32 pinmask, uint8 enable);
00405 
00406 #ifdef __cplusplus
00407 }
00408 #endif
00409 
00410 
00411 #endif /* _M2M_PERIPH_H_ */
00412