SAMV71 Xplained Ultra Software Package 1.5

twi.c

Go to the documentation of this file.
00001 /* ---------------------------------------------------------------------------- */
00002 /*                  Atmel Microcontroller Software Support                      */
00003 /*                       SAM Software Package License                           */
00004 /* ---------------------------------------------------------------------------- */
00005 /* Copyright (c) 2015, Atmel Corporation                                        */
00006 /*                                                                              */
00007 /* All rights reserved.                                                         */
00008 /*                                                                              */
00009 /* Redistribution and use in source and binary forms, with or without           */
00010 /* modification, are permitted provided that the following condition is met:    */
00011 /*                                                                              */
00012 /* - Redistributions of source code must retain the above copyright notice,     */
00013 /* this list of conditions and the disclaimer below.                            */
00014 /*                                                                              */
00015 /* Atmel's name may not be used to endorse or promote products derived from     */
00016 /* this software without specific prior written permission.                     */
00017 /*                                                                              */
00018 /* DISCLAIMER:  THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR   */
00019 /* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF */
00020 /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE   */
00021 /* DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,      */
00022 /* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT */
00023 /* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,  */
00024 /* OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF    */
00025 /* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING         */
00026 /* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, */
00027 /* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                           */
00028 /* ---------------------------------------------------------------------------- */
00029 
00030 /** \addtogroup twi_module Working with TWI
00031  *  \ingroup peripherals_module
00032  * The TWI driver provides the interface to configure and use the TWI
00033  * peripheral.
00034  *
00035  * \section Usage
00036  * <ul>
00037  * <li> Configures a TWI peripheral to operate in master mode, at the given
00038  * frequency (in Hz) using TWI_Configure(). </li>
00039  * <li> Sends a STOP condition on the TWI using TWI_Stop().</li>
00040  * <li> Starts a read operation on the TWI bus with the specified slave using
00041  * TWI_StartRead(). Data must then be read using TWI_ReadByte() whenever
00042  * a byte is available (poll using TWI_ByteReceived()).</li>
00043  * <li> Starts a write operation on the TWI to access the selected slave using
00044  * TWI_StartWrite(). A byte of data must be provided to start the write;
00045  * other bytes are written next.</li>
00046  * <li> Sends a byte of data to one of the TWI slaves on the bus using
00047  * TWI_WriteByte().
00048  * This function must be called once before TWI_StartWrite() with the first
00049  * byte of data
00050  * to send, then it shall be called repeatedly after that to send the
00051  * remaining bytes.</li>
00052  * <li> Check if a byte has been received and can be read on the given TWI
00053  * peripheral using TWI_ByteReceived().<
00054  * Check if a byte has been sent using TWI_ByteSent().</li>
00055  * <li> Check if the current transmission is complete (the STOP has been sent)
00056  * using TWI_TransferComplete().</li>
00057  * <li> Enables & disable the selected interrupts sources on a TWI peripheral
00058  * using TWI_EnableIt() and TWI_DisableIt().</li>
00059  * <li> Get current status register of the given TWI peripheral using
00060  * TWI_GetStatus(). Get current status register of the given TWI peripheral, but
00061  * masking interrupt sources which are not currently enabled using
00062  * TWI_GetMaskedStatus().</li>
00063  * </ul>
00064  * For more accurate information, please look at the TWI section of the
00065  * Datasheet.
00066  *
00067  * Related files :\n
00068  * \ref twi.c\n
00069  * \ref twi.h.\n
00070  */
00071 /*@{*/
00072 /*@}*/
00073 
00074 /**
00075  * \file
00076  *
00077  * Implementation of Two Wire Interface (TWI).
00078  *
00079  */
00080 
00081 /*----------------------------------------------------------------------------
00082  *        Headers
00083  *----------------------------------------------------------------------------*/
00084 
00085 #include "chip.h"
00086 
00087 #include <assert.h>
00088 
00089 #define TWIHS_IT    (TWIHS_IER_TXCOMP | TWIHS_IER_TXCOMP | TWIHS_IER_RXRDY \
00090                       | TWIHS_IER_TXRDY | TWIHS_IER_SVACC | TWIHS_IER_GACC | \
00091                       TWIHS_IER_OVRE | TWIHS_IER_UNRE | TWIHS_IER_NACK | \
00092                       TWIHS_IER_ARBLST | TWIHS_IER_SCL_WS | TWIHS_IER_EOSACC | \
00093                       TWIHS_IER_MCACK | TWIHS_IER_TOUT | TWIHS_IER_PECERR |\
00094                       TWIHS_IER_SMBDAM | TWIHS_IER_SMBHHM)
00095 
00096 
00097 /** variable for control thether or not to set both START and STOP
00098   * In single data byte master read, the START and STOP must both be set */
00099 uint32_t twi_send_stop = 0;
00100 
00101 /*----------------------------------------------------------------------------
00102  *        Exported functions
00103  *----------------------------------------------------------------------------*/
00104 
00105 /**
00106  * \brief Configures a TWI peripheral to operate in master mode, at the given
00107  * frequency (in Hz). The duty cycle of the TWI clock is set to 50%.
00108  * \param pTwi  Pointer to an Twihs instance.
00109  * \param twck  Desired TWI clock frequency.
00110  * \param mck  Master clock frequency.
00111  */
00112 void TWI_ConfigureMaster(Twihs *pTwi, uint32_t dwTwCk, uint32_t dwMCk)
00113 {
00114     uint32_t dwCkDiv = 0;
00115     uint32_t dwClDiv;
00116     uint32_t dwOk = 0;
00117 
00118     TRACE_DEBUG("TWI_ConfigureMaster()\n\r");
00119     assert(pTwi);
00120 
00121     /* Reset the TWI */
00122     pTwi->TWIHS_CR = TWIHS_CR_SWRST;
00123 
00124     /* Configure clock */
00125     while (!dwOk) {
00126         dwClDiv = ((dwMCk / (2 * dwTwCk)) - 4) / (1 << dwCkDiv);
00127 
00128         if (dwClDiv <= 255)
00129             dwOk = 1;
00130         else
00131             dwCkDiv++;
00132     }
00133 
00134     assert(dwCkDiv < 8);
00135     TRACE_DEBUG("Using CKDIV = %u and CLDIV/CHDIV = %u\n\r", dwCkDiv, dwClDiv);
00136 
00137     pTwi->TWIHS_CWGR = (dwCkDiv << 16) | (dwClDiv << 8) | dwClDiv;
00138 
00139     /* TWI Slave Mode Disabled. */
00140     pTwi->TWIHS_CR = TWIHS_CR_SVDIS;
00141 
00142     /* Set master mode */
00143     pTwi->TWIHS_CR = TWIHS_CR_MSEN;
00144 }
00145 
00146 /**
00147  * \brief Configures a TWI peripheral to operate in slave mode.
00148  * \param pTwi  Pointer to an Twihs instance.
00149  * \param slaveAddress Slave address.
00150  */
00151 void TWI_ConfigureSlave(Twihs *pTwi, uint8_t slaveAddress)
00152 {
00153     /* TWI software reset */
00154     pTwi->TWIHS_CR = TWIHS_CR_SWRST;
00155 
00156     /* Configure slave address. */
00157     pTwi->TWIHS_SMR = TWIHS_SMR_SADR(slaveAddress);
00158 
00159     /* TWI Master Mode Disabled*/
00160     pTwi->TWIHS_CR = TWIHS_CR_MSDIS;
00161 
00162     /* SVEN: TWI Slave Mode Enabled */
00163     pTwi->TWIHS_CR = TWIHS_CR_SVEN;
00164 
00165     assert((pTwi->TWIHS_CR & TWIHS_CR_SVDIS) != TWIHS_CR_SVDIS);
00166 }
00167 
00168 /**
00169  * \brief Sends a STOP condition on the TWI.
00170  * \param pTwi  Pointer to an Twihs instance.
00171  */
00172 void TWI_Stop(Twihs *pTwi)
00173 {
00174     assert(pTwi != NULL);
00175 
00176     pTwi->TWIHS_CR = TWIHS_CR_STOP;
00177 }
00178 
00179 /**
00180  * \brief Starts a read operation on the TWI bus with the specified slave, it
00181  * returns immediately. Data must then be read using TWI_ReadByte() whenever a
00182  * byte is available (poll using TWI_ByteReceived()).
00183  * \param pTwi  Pointer to an Twihs instance.
00184  * \param address  Slave address on the bus.
00185  * \param iaddress  Optional internal address bytes.
00186  * \param isize  Number of internal address bytes.
00187  */
00188 void TWI_StartRead(
00189     Twihs *pTwi,
00190     uint8_t address,
00191     uint32_t iaddress,
00192     uint8_t isize)
00193 {
00194     assert(pTwi != NULL);
00195     assert((address & 0x80) == 0);
00196     assert((iaddress & 0xFF000000) == 0);
00197     assert(isize < 4);
00198 
00199     /* Set slave address and number of internal address bytes. */
00200     pTwi->TWIHS_MMR = 0;
00201     pTwi->TWIHS_MMR = (isize << 8) | TWIHS_MMR_MREAD | (address << 16);
00202 
00203     /* Set internal address bytes */
00204     pTwi->TWIHS_IADR = 0;
00205     pTwi->TWIHS_IADR = iaddress;
00206 
00207     /* Send START condition */
00208     if (0 == twi_send_stop)
00209         pTwi->TWIHS_CR = TWIHS_CR_START;
00210     else {
00211         twi_send_stop = 0;
00212         pTwi->TWIHS_CR = TWIHS_CR_START | TWIHS_CR_STOP;
00213     }
00214 }
00215 
00216 /**
00217  * \brief Reads a byte from the TWI bus. The read operation must have been started
00218  * using TWI_StartRead() and a byte must be available (check with TWI_ByteReceived()).
00219  * \param pTwi  Pointer to an Twihs instance.
00220  * \return byte read.
00221  */
00222 uint8_t TWI_ReadByte(Twihs *pTwi)
00223 {
00224     assert(pTwi != NULL);
00225 
00226     return pTwi->TWIHS_RHR;
00227 }
00228 
00229 /**
00230  * \brief Sends a byte of data to one of the TWI slaves on the bus.
00231  * \note This function must be called once before TWI_StartWrite() with
00232  * the first byte of data  to send, then it shall be called repeatedly
00233  * after that to send the remaining bytes.
00234  * \param pTwi  Pointer to an Twihs instance.
00235  * \param byte  Byte to send.
00236  */
00237 void TWI_WriteByte(Twihs *pTwi, uint8_t byte)
00238 {
00239     assert(pTwi != NULL);
00240 
00241     pTwi->TWIHS_THR = byte;
00242 }
00243 
00244 /**
00245  * \brief Starts a write operation on the TWI to access the selected slave, then
00246  *  returns immediately. A byte of data must be provided to start the write;
00247  * other bytes are written next.
00248  * after that to send the remaining bytes.
00249  * \param pTwi  Pointer to an Twihs instance.
00250  * \param address  Address of slave to acccess on the bus.
00251  * \param iaddress  Optional slave internal address.
00252  * \param isize  Number of internal address bytes.
00253  * \param byte  First byte to send.
00254  */
00255 void TWI_StartWrite(
00256     Twihs *pTwi,
00257     uint8_t address,
00258     uint32_t iaddress,
00259     uint8_t isize,
00260     uint8_t byte)
00261 {
00262     assert(pTwi != NULL);
00263     assert((address & 0x80) == 0);
00264     assert((iaddress & 0xFF000000) == 0);
00265     assert(isize < 4);
00266 
00267     /* Set slave address and number of internal address bytes. */
00268     pTwi->TWIHS_MMR = 0;
00269     pTwi->TWIHS_MMR = (isize << 8) | (address << 16);
00270 
00271     /* Set internal address bytes. */
00272     pTwi->TWIHS_IADR = 0;
00273     pTwi->TWIHS_IADR = iaddress;
00274 
00275     /* Write first byte to send.*/
00276     TWI_WriteByte(pTwi, byte);
00277 }
00278 
00279 /**
00280  * \brief Check if a byte have been received from TWI.
00281  * \param pTwi  Pointer to an Twihs instance.
00282  * \return 1 if a byte has been received and can be read on the given TWI
00283  * peripheral; otherwise, returns 0. This function resets the status register.
00284  */
00285 uint8_t TWI_ByteReceived(Twihs *pTwi)
00286 {
00287     return ((pTwi->TWIHS_SR & TWIHS_SR_RXRDY) == TWIHS_SR_RXRDY);
00288 }
00289 
00290 /**
00291  * \brief Check if a byte have been sent to TWI.
00292  * \param pTwi  Pointer to an Twihs instance.
00293  * \return 1 if a byte has been sent  so another one can be stored for
00294  * transmission; otherwise returns 0. This function clears the status register.
00295  */
00296 uint8_t TWI_ByteSent(Twihs *pTwi)
00297 {
00298     return ((pTwi->TWIHS_SR & TWIHS_SR_TXRDY) == TWIHS_SR_TXRDY);
00299 }
00300 
00301 /**
00302  * \brief Check if current transmission is completed.
00303  * \param pTwi  Pointer to an Twihs instance.
00304  * \return  1 if the current transmission is complete (the STOP has been sent);
00305  * otherwise returns 0.
00306  */
00307 uint8_t TWI_TransferComplete(Twihs *pTwi)
00308 {
00309     return ((pTwi->TWIHS_SR & TWIHS_SR_TXCOMP) == TWIHS_SR_TXCOMP);
00310 }
00311 
00312 /**
00313  * \brief Enables the selected interrupts sources on a TWI peripheral.
00314  * \param pTwi  Pointer to an Twihs instance.
00315  * \param sources  Bitwise OR of selected interrupt sources.
00316  */
00317 void TWI_EnableIt(Twihs *pTwi, uint32_t sources)
00318 {
00319     assert(pTwi != NULL);
00320     assert((sources & TWIHS_IT));
00321 
00322     pTwi->TWIHS_IER = sources;
00323 }
00324 
00325 /**
00326  * \brief Disables the selected interrupts sources on a TWI peripheral.
00327  * \param pTwi  Pointer to an Twihs instance.
00328  * \param sources  Bitwise OR of selected interrupt sources.
00329  */
00330 void TWI_DisableIt(Twihs *pTwi, uint32_t sources)
00331 {
00332     assert(pTwi != NULL);
00333     assert(sources & TWIHS_IT);
00334 
00335     pTwi->TWIHS_IDR = sources;
00336 }
00337 
00338 /**
00339  * \brief Get the current status register of the given TWI peripheral.
00340  * \note This resets the internal value of the status register, so further
00341  * read may yield different values.
00342  * \param pTwi  Pointer to an Twihs instance.
00343  * \return  TWI status register.
00344  */
00345 uint32_t TWI_GetStatus(Twihs *pTwi)
00346 {
00347     assert(pTwi != NULL);
00348 
00349     return pTwi->TWIHS_SR;
00350 }
00351 
00352 /**
00353  * \brief Returns the current status register of the given TWI peripheral, but
00354  * masking interrupt sources which are not currently enabled.
00355  * \note This resets the internal value of the status register, so further
00356  * read may yield different values.
00357  * \param pTwi  Pointer to an Twihs instance.
00358  */
00359 uint32_t TWI_GetMaskedStatus(Twihs *pTwi)
00360 {
00361     uint32_t status;
00362 
00363     assert(pTwi != NULL);
00364 
00365     status = pTwi->TWIHS_SR;
00366     status &= pTwi->TWIHS_IMR;
00367 
00368     return status;
00369 }
00370 
00371 /**
00372  * \brief  Sends a STOP condition. STOP Condition is sent just after completing
00373  *  the current byte transmission in master read mode.
00374  * \param pTwi  Pointer to an Twihs instance.
00375  */
00376 void TWI_SendSTOPCondition(Twihs *pTwi)
00377 {
00378     assert(pTwi != NULL);
00379 
00380     pTwi->TWIHS_CR |= TWIHS_CR_STOP;
00381 }
00382 
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines