Xmega Application Note | |||||
#include "avr_compiler.h"
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. |
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.
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 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 |
#define TWIM_STATUS_READY 0 |
Transaction status defines.
Definition at line 69 of file twi_master_driver.h.
Referenced by main(), TWI_MasterArbitrationLostBusErrorHandler(), TWI_MasterReady(), TWI_MasterTransactionFinished(), TWI_MasterWriteHandler(), and TWI_MasterWriteRead().
#define TWIM_WRITE_BUFFER_SIZE 8 |
Buffer size defines
Definition at line 85 of file twi_master_driver.h.
Referenced by TWI_MasterWriteRead().
typedef struct TWI_Master TWI_Master_t |
TWI master driver struct.
TWI master struct. Holds pointer to TWI module, buffers and necessary varibles.
typedef enum TWIM_RESULT_enum TWIM_RESULT_t |
Transaction result enumeration.
enum TWIM_RESULT_enum |
Transaction result enumeration.
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;
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.
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.
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.
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 }
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.
twi | The TWI_Master_t struct instance. | |
address | The slave address. | |
bytesToRead | The number of bytes to read. |
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 }
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.
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 }
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.
twi | The TWI_Master_t struct instance. |
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.
twi | The TWI_Master_t struct instance. |
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.
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.
twi | The TWI_Master_t struct instance. | |
address | Slave address. | |
writeData | Pointer to data to write. | |
bytesToWrite | Number of data bytes to write. |
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 }
void TWI_MasterWriteHandler | ( | TWI_Master_t * | twi | ) |
TWI master write interrupt handler.
Handles TWI transactions (master write) and responses to (N)ACK.
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 }
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.
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. |
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 }
Generated on Tue Aug 11 12:42:13 2009 for AVR1308 Using the XMEGA TWI by ![]() |