Xmega Application Note


twi_master_driver.h File Reference

XMEGA TWI master driver header file. More...

#include "avr_compiler.h"

Include dependency graph for twi_master_driver.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  TWI_Master
 TWI master driver struct. More...

Defines

#define TWI_BAUD(F_SYS, F_TWI)   ((F_SYS / (2 * F_TWI)) - 5)
#define TWIM_READ_BUFFER_SIZE   8
#define TWIM_STATUS_BUSY   1
#define TWIM_STATUS_READY   0
#define TWIM_WRITE_BUFFER_SIZE   8

Typedefs

typedef struct TWI_Master TWI_Master_t
 TWI master driver struct.
typedef enum TWIM_RESULT_enum TWIM_RESULT_t

Enumerations

enum  TWIM_RESULT_enum {
  TWIM_RESULT_UNKNOWN = (0x00<<0), TWIM_RESULT_OK = (0x01<<0), TWIM_RESULT_BUFFER_OVERFLOW = (0x02<<0), TWIM_RESULT_ARBITRATION_LOST = (0x03<<0),
  TWIM_RESULT_BUS_ERROR = (0x04<<0), TWIM_RESULT_NACK_RECEIVED = (0x05<<0), TWIM_RESULT_FAIL = (0x06<<0)
}

Functions

void TWI_MasterArbitrationLostBusErrorHandler (TWI_Master_t *twi)
 TWI master arbitration lost and bus error interrupt handler.
void TWI_MasterInit (TWI_Master_t *twi, TWI_t *module, TWI_MASTER_INTLVL_t intLevel, uint8_t baudRateRegisterSetting)
 Initialize the TWI module.
void TWI_MasterInterruptHandler (TWI_Master_t *twi)
 Common TWI master interrupt service routine.
bool TWI_MasterRead (TWI_Master_t *twi, uint8_t address, uint8_t bytesToRead)
 TWI read transaction.
void TWI_MasterReadHandler (TWI_Master_t *twi)
 TWI master read interrupt handler.
bool TWI_MasterReady (TWI_Master_t *twi)
 Returns true if transaction is ready.
TWI_MASTER_BUSSTATE_t TWI_MasterState (TWI_Master_t *twi)
 Returns the TWI bus state.
void TWI_MasterTransactionFinished (TWI_Master_t *twi, uint8_t result)
 TWI transaction finished handler.
bool TWI_MasterWrite (TWI_Master_t *twi, uint8_t address, uint8_t *writeData, uint8_t bytesToWrite)
 TWI write transaction.
void TWI_MasterWriteHandler (TWI_Master_t *twi)
 TWI master write interrupt handler.
bool TWI_MasterWriteRead (TWI_Master_t *twi, uint8_t address, uint8_t *writeData, uint8_t bytesToWrite, uint8_t bytesToRead)
 TWI write and/or read transaction.


Detailed Description

XMEGA TWI master driver header file.

This file contains the function prototypes and enumerator definitions for various configuration parameters for the XMEGA TWI master driver.

The driver is not intended for size and/or speed critical code, since most functions are just a few lines of code, and the function call overhead would decrease code performance. The driver is intended for rapid prototyping and documentation purposes for getting started with the XMEGA TWI master module.

For size and/or speed critical code, it is recommended to copy the function contents directly into your application instead of making a function call.

Application note:
AVR1308: Using the XMEGA TWI
Documentation
For comprehensive code documentation, supported compilers, compiler settings and supported devices see readme.html
Author:
Atmel Corporation: http://www.atmel.com
Support email: avr@atmel.com
Revision
1569
Date
2008-04-22 13:03:43 +0200 (ti, 22 apr 2008)

Copyright (c) 2008, Atmel Corporation All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The name of ATMEL may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Definition in file twi_master_driver.h.


Define Documentation

#define TWI_BAUD ( F_SYS,
F_TWI   )     ((F_SYS / (2 * F_TWI)) - 5)

Baud register setting calculation. Formula described in datasheet.

Definition at line 65 of file twi_master_driver.h.

#define TWIM_READ_BUFFER_SIZE   8

Definition at line 86 of file twi_master_driver.h.

Referenced by TWI_MasterReadHandler(), and TWI_MasterWriteRead().

#define TWIM_STATUS_BUSY   1

Definition at line 70 of file twi_master_driver.h.

Referenced by TWI_MasterWriteRead().

#define TWIM_STATUS_READY   0

#define TWIM_WRITE_BUFFER_SIZE   8

Buffer size defines

Definition at line 85 of file twi_master_driver.h.

Referenced by TWI_MasterWriteRead().


Typedef Documentation

typedef struct TWI_Master TWI_Master_t

TWI master driver struct.

TWI master struct. Holds pointer to TWI module, buffers and necessary varibles.

Transaction result enumeration.


Enumeration Type Documentation

Transaction result enumeration.

Enumerator:
TWIM_RESULT_UNKNOWN 
TWIM_RESULT_OK 
TWIM_RESULT_BUFFER_OVERFLOW 
TWIM_RESULT_ARBITRATION_LOST 
TWIM_RESULT_BUS_ERROR 
TWIM_RESULT_NACK_RECEIVED 
TWIM_RESULT_FAIL 

Definition at line 74 of file twi_master_driver.h.

00074                               {
00075         TWIM_RESULT_UNKNOWN          = (0x00<<0),
00076         TWIM_RESULT_OK               = (0x01<<0),
00077         TWIM_RESULT_BUFFER_OVERFLOW  = (0x02<<0),
00078         TWIM_RESULT_ARBITRATION_LOST = (0x03<<0),
00079         TWIM_RESULT_BUS_ERROR        = (0x04<<0),
00080         TWIM_RESULT_NACK_RECEIVED    = (0x05<<0),
00081         TWIM_RESULT_FAIL             = (0x06<<0),
00082 } TWIM_RESULT_t;


Function Documentation

void TWI_MasterArbitrationLostBusErrorHandler ( TWI_Master_t twi  ) 

TWI master arbitration lost and bus error interrupt handler.

Handles TWI responses to lost arbitration and bus error.

Parameters:
twi The TWI_Master_t struct instance.

Definition at line 287 of file twi_master_driver.c.

References TWI_Master::interface, TWI_Master::result, TWI_Master::status, TWIM_RESULT_ARBITRATION_LOST, TWIM_RESULT_BUS_ERROR, and TWIM_STATUS_READY.

Referenced by TWI_MasterInterruptHandler().

00288 {
00289         uint8_t currentStatus = twi->interface->MASTER.STATUS;
00290 
00291         /* If bus error. */
00292         if (currentStatus & TWI_MASTER_BUSERR_bm) {
00293                 twi->result = TWIM_RESULT_BUS_ERROR;
00294         }
00295         /* If arbitration lost. */
00296         else {
00297                 twi->result = TWIM_RESULT_ARBITRATION_LOST;
00298         }
00299 
00300         /* Clear interrupt flag. */
00301         twi->interface->MASTER.STATUS = currentStatus | TWI_MASTER_ARBLOST_bm;
00302 
00303         twi->status = TWIM_STATUS_READY;
00304 }

void TWI_MasterInit ( TWI_Master_t twi,
TWI_t *  module,
TWI_MASTER_INTLVL_t  intLevel,
uint8_t  baudRateRegisterSetting 
)

Initialize the TWI module.

TWI module initialization function. Enables master read and write interrupts. Remember to enable interrupts globally from the main application.

Parameters:
twi The TWI_Master_t struct instance.
module The TWI module to use.
intLevel Master interrupt level.
baudRateRegisterSetting The baud rate register value.

Definition at line 83 of file twi_master_driver.c.

References TWI_Master::interface.

Referenced by main().

00087 {
00088         twi->interface = module;
00089         twi->interface->MASTER.CTRLA = intLevel |
00090                                        TWI_MASTER_RIEN_bm |
00091                                        TWI_MASTER_WIEN_bm |
00092                                        TWI_MASTER_ENABLE_bm;
00093         twi->interface->MASTER.BAUD = baudRateRegisterSetting;
00094         twi->interface->MASTER.STATUS = TWI_MASTER_BUSSTATE_IDLE_gc;
00095 }

void TWI_MasterInterruptHandler ( TWI_Master_t twi  ) 

Common TWI master interrupt service routine.

Check current status and calls the appropriate handler.

Parameters:
twi The TWI_Master_t struct instance.

Definition at line 253 of file twi_master_driver.c.

References TWI_Master::interface, TWI_MasterArbitrationLostBusErrorHandler(), TWI_MasterReadHandler(), TWI_MasterTransactionFinished(), TWI_MasterWriteHandler(), and TWIM_RESULT_FAIL.

Referenced by ISR().

00254 {
00255         uint8_t currentStatus = twi->interface->MASTER.STATUS;
00256 
00257         /* If arbitration lost or bus error. */
00258         if ((currentStatus & TWI_MASTER_ARBLOST_bm) ||
00259             (currentStatus & TWI_MASTER_BUSERR_bm)) {
00260 
00261                 TWI_MasterArbitrationLostBusErrorHandler(twi);
00262         }
00263 
00264         /* If master write interrupt. */
00265         else if (currentStatus & TWI_MASTER_WIF_bm) {
00266                 TWI_MasterWriteHandler(twi);
00267         }
00268 
00269         /* If master read interrupt. */
00270         else if (currentStatus & TWI_MASTER_RIF_bm) {
00271                 TWI_MasterReadHandler(twi);
00272         }
00273 
00274         /* If unexpected state. */
00275         else {
00276                 TWI_MasterTransactionFinished(twi, TWIM_RESULT_FAIL);
00277         }
00278 }

Here is the call graph for this function:

bool TWI_MasterRead ( TWI_Master_t twi,
uint8_t  address,
uint8_t  bytesToRead 
)

TWI read transaction.

This function is a TWI Maste wrapper for read-only transaction.

Parameters:
twi The TWI_Master_t struct instance.
address The slave address.
bytesToRead The number of bytes to read.
Return values:
true If transaction could be started.
false If transaction could not be started.

Definition at line 169 of file twi_master_driver.c.

References TWI_MasterWriteRead().

00172 {
00173         bool twi_status = TWI_MasterWriteRead(twi, address, 0, 0, bytesToRead);
00174         return twi_status;
00175 }

Here is the call graph for this function:

void TWI_MasterReadHandler ( TWI_Master_t twi  ) 

TWI master read interrupt handler.

This is the master read interrupt handler that takes care of reading bytes from the TWI slave.

Parameters:
twi The TWI_Master_t struct instance.

Definition at line 356 of file twi_master_driver.c.

References TWI_Master::bytesRead, TWI_Master::bytesToRead, TWI_Master::interface, TWI_Master::readData, TWI_MasterTransactionFinished(), TWIM_READ_BUFFER_SIZE, TWIM_RESULT_BUFFER_OVERFLOW, and TWIM_RESULT_OK.

Referenced by TWI_MasterInterruptHandler().

00357 {
00358         /* Fetch data if bytes to be read. */
00359         if (twi->bytesRead < TWIM_READ_BUFFER_SIZE) {
00360                 uint8_t data = twi->interface->MASTER.DATA;
00361                 twi->readData[twi->bytesRead] = data;
00362                 twi->bytesRead++;
00363         }
00364 
00365         /* If buffer overflow, issue STOP and BUFFER_OVERFLOW condition. */
00366         else {
00367                 twi->interface->MASTER.CTRLC = TWI_MASTER_CMD_STOP_gc;
00368                 TWI_MasterTransactionFinished(twi, TWIM_RESULT_BUFFER_OVERFLOW);
00369         }
00370 
00371         /* Local variable used in if test to avoid compiler warning. */
00372         uint8_t bytesToRead = twi->bytesToRead;
00373 
00374         /* If more bytes to read, issue ACK and start a byte read. */
00375         if (twi->bytesRead < bytesToRead) {
00376                 twi->interface->MASTER.CTRLC = TWI_MASTER_CMD_RECVTRANS_gc;
00377         }
00378 
00379         /* If transaction finished, issue NACK and STOP condition. */
00380         else {
00381                 twi->interface->MASTER.CTRLC = TWI_MASTER_ACKACT_bm |
00382                                                TWI_MASTER_CMD_STOP_gc;
00383                 TWI_MasterTransactionFinished(twi, TWIM_RESULT_OK);
00384         }
00385 }

Here is the call graph for this function:

bool TWI_MasterReady ( TWI_Master_t twi  ) 

Returns true if transaction is ready.

This function returns a boolean whether the TWI Master is ready for a new transaction.

Parameters:
twi The TWI_Master_t struct instance.
Return values:
true If transaction could be started.
false If transaction could not be started.

Definition at line 129 of file twi_master_driver.c.

References TWI_Master::status, and TWIM_STATUS_READY.

00130 {
00131         bool twi_status = (twi->status & TWIM_STATUS_READY);
00132         return twi_status;
00133 }

TWI_MASTER_BUSSTATE_t TWI_MasterState ( TWI_Master_t twi  ) 

Returns the TWI bus state.

Returns the TWI bus state (type defined in device headerfile), unknown, idle, owner or busy.

Parameters:
twi The TWI_Master_t struct instance.
Return values:
TWI_MASTER_BUSSTATE_UNKNOWN_gc Bus state is unknown.
TWI_MASTER_BUSSTATE_IDLE_gc Bus state is idle.
TWI_MASTER_BUSSTATE_OWNER_gc Bus state is owned by the master.
TWI_MASTER_BUSSTATE_BUSY_gc Bus state is busy.

Definition at line 110 of file twi_master_driver.c.

References TWI_Master::interface.

00111 {
00112         TWI_MASTER_BUSSTATE_t twi_status;
00113         twi_status = (TWI_MASTER_BUSSTATE_t) (twi->interface->MASTER.STATUS &
00114                                               TWI_MASTER_BUSSTATE_gm);
00115         return twi_status;
00116 }

void TWI_MasterTransactionFinished ( TWI_Master_t twi,
uint8_t  result 
)

TWI transaction finished handler.

Prepares module for new transaction.

Parameters:
twi The TWI_Master_t struct instance.
result The result of the operation.

Definition at line 395 of file twi_master_driver.c.

References TWI_Master::result, TWI_Master::status, and TWIM_STATUS_READY.

Referenced by TWI_MasterInterruptHandler(), TWI_MasterReadHandler(), and TWI_MasterWriteHandler().

00396 {
00397         twi->result = result;
00398         twi->status = TWIM_STATUS_READY;
00399 }

bool TWI_MasterWrite ( TWI_Master_t twi,
uint8_t  address,
uint8_t *  writeData,
uint8_t  bytesToWrite 
)

TWI write transaction.

This function is TWI Master wrapper for a write-only transaction.

Parameters:
twi The TWI_Master_t struct instance.
address Slave address.
writeData Pointer to data to write.
bytesToWrite Number of data bytes to write.
Return values:
true If transaction could be started.
false If transaction could not be started.

Definition at line 148 of file twi_master_driver.c.

References TWI_MasterWriteRead().

00152 {
00153         bool twi_status = TWI_MasterWriteRead(twi, address, writeData, bytesToWrite, 0);
00154         return twi_status;
00155 }

Here is the call graph for this function:

void TWI_MasterWriteHandler ( TWI_Master_t twi  ) 

TWI master write interrupt handler.

Handles TWI transactions (master write) and responses to (N)ACK.

Parameters:
twi The TWI_Master_t struct instance.

Definition at line 313 of file twi_master_driver.c.

References TWI_Master::address, TWI_Master::bytesRead, TWI_Master::bytesToRead, TWI_Master::bytesToWrite, TWI_Master::bytesWritten, TWI_Master::interface, TWI_Master::result, TWI_Master::status, TWI_MasterTransactionFinished(), TWIM_RESULT_NACK_RECEIVED, TWIM_RESULT_OK, TWIM_STATUS_READY, and TWI_Master::writeData.

Referenced by TWI_MasterInterruptHandler().

00314 {
00315         /* Local variables used in if tests to avoid compiler warning. */
00316         uint8_t bytesToWrite  = twi->bytesToWrite;
00317         uint8_t bytesToRead   = twi->bytesToRead;
00318 
00319         /* If NOT acknowledged (NACK) by slave cancel the transaction. */
00320         if (twi->interface->MASTER.STATUS & TWI_MASTER_RXACK_bm) {
00321                 twi->interface->MASTER.CTRLC = TWI_MASTER_CMD_STOP_gc;
00322                 twi->result = TWIM_RESULT_NACK_RECEIVED;
00323                 twi->status = TWIM_STATUS_READY;
00324         }
00325 
00326         /* If more bytes to write, send data. */
00327         else if (twi->bytesWritten < bytesToWrite) {
00328                 uint8_t data = twi->writeData[twi->bytesWritten];
00329                 twi->interface->MASTER.DATA = data;
00330                 ++twi->bytesWritten;
00331         }
00332 
00333         /* If bytes to read, send repeated START condition + Address +
00334          * 'R/_W = 1'
00335          */
00336         else if (twi->bytesRead < bytesToRead) {
00337                 uint8_t readAddress = twi->address | 0x01;
00338                 twi->interface->MASTER.ADDR = readAddress;
00339         }
00340 
00341         /* If transaction finished, send STOP condition and set RESULT OK. */
00342         else {
00343                 twi->interface->MASTER.CTRLC = TWI_MASTER_CMD_STOP_gc;
00344                 TWI_MasterTransactionFinished(twi, TWIM_RESULT_OK);
00345         }
00346 }

Here is the call graph for this function:

bool TWI_MasterWriteRead ( TWI_Master_t twi,
uint8_t  address,
uint8_t *  writeData,
uint8_t  bytesToWrite,
uint8_t  bytesToRead 
)

TWI write and/or read transaction.

This function is a TWI Master write and/or read transaction. The function can be used to both write and/or read bytes to/from the TWI Slave in one transaction.

Parameters:
twi The TWI_Master_t struct instance.
address The slave address.
writeData Pointer to data to write.
bytesToWrite Number of bytes to write.
bytesToRead Number of bytes to read.
Return values:
true If transaction could be started.
false If transaction could not be started.

Definition at line 193 of file twi_master_driver.c.

References TWI_Master::address, TWI_Master::bytesRead, TWI_Master::bytesToRead, TWI_Master::bytesToWrite, TWI_Master::bytesWritten, TWI_Master::interface, TWI_Master::result, TWI_Master::status, TWIM_READ_BUFFER_SIZE, TWIM_RESULT_UNKNOWN, TWIM_STATUS_BUSY, TWIM_STATUS_READY, TWIM_WRITE_BUFFER_SIZE, and TWI_Master::writeData.

Referenced by main(), TWI_MasterRead(), and TWI_MasterWrite().

00198 {
00199         /*Parameter sanity check. */
00200         if (bytesToWrite > TWIM_WRITE_BUFFER_SIZE) {
00201                 return false;
00202         }
00203         if (bytesToRead > TWIM_READ_BUFFER_SIZE) {
00204                 return false;
00205         }
00206 
00207         /*Initiate transaction if bus is ready. */
00208         if (twi->status == TWIM_STATUS_READY) {
00209 
00210                 twi->status = TWIM_STATUS_BUSY;
00211                 twi->result = TWIM_RESULT_UNKNOWN;
00212 
00213                 twi->address = address<<1;
00214 
00215                 /* Fill write data buffer. */
00216                 for (uint8_t bufferIndex=0; bufferIndex < bytesToWrite; bufferIndex++) {
00217                         twi->writeData[bufferIndex] = writeData[bufferIndex];
00218                 }
00219 
00220                 twi->bytesToWrite = bytesToWrite;
00221                 twi->bytesToRead = bytesToRead;
00222                 twi->bytesWritten = 0;
00223                 twi->bytesRead = 0;
00224 
00225                 /* If write command, send the START condition + Address +
00226                  * 'R/_W = 0'
00227                  */
00228                 if (twi->bytesToWrite > 0) {
00229                         uint8_t writeAddress = twi->address & ~0x01;
00230                         twi->interface->MASTER.ADDR = writeAddress;
00231                 }
00232 
00233                 /* If read command, send the START condition + Address +
00234                  * 'R/_W = 1'
00235                  */
00236                 else if (twi->bytesToRead > 0) {
00237                         uint8_t readAddress = twi->address | 0x01;
00238                         twi->interface->MASTER.ADDR = readAddress;
00239                 }
00240                 return true;
00241         } else {
00242                 return false;
00243         }
00244 }

@DOC_TITLE@
Generated on Tue Aug 11 12:42:13 2009 for AVR1308 Using the XMEGA TWI by doxygen 1.5.9