# twi.h File Reference

## Detailed Description

TWI driver for AVR32 UC3.

This file defines a useful set of functions for TWI on AVR32 devices.

- Compiler: IAR EWAVR32 and GNU GCC for AVR32
- Supported devices: All AVR32 devices with a TWI module can be used.
- AppNote:

Author:
  Atmel Corporation: http://www.atmel.com
  Support and FAQ: http://support.atmel.no/

Definition in file twi.h.

`#include <avr32/io.h>`
`#include "compiler.h"`

Go to the source code of this file.

## Data Structures
struct | twi_options_t
| Input parameters when initializing the twi module mode. More...
struct | twi_package_t
| Information concerning the data transmission. More...
struct | twi_slave_fct_t
| Pointer on TWI slave application routines. More...
## Defines
Error Codes for the Module
#define | TWI_ARBITRATION_LOST -2
#define | TWI_INVALID_ARGUMENT -1
#define | TWI_NO_CHIP_FOUND -3
#define | TWI_RECEIVE_NACK -5
#define | TWI_RECEIVE_OVERRUN -4
#define | TWI_SEND_NACK -7
#define | TWI_SEND_OVERRUN -6
#define | TWI_SUCCESS 0
## Functions
void | twi_disable_interrupt (volatile avr32_twi_t *twi)
| Disable all TWI interrupts.
int | twi_master_init (volatile avr32_twi_t *twi, const twi_options_t *opt)
| Initialize the twi master module.
int | twi_master_read (volatile avr32_twi_t *twi, const twi_package_t *package)
| Read multiple bytes from a TWI compatible slave device.
int | twi_master_write (volatile avr32_twi_t *twi, const twi_package_t *package)
| Write multiple bytes to a TWI compatible slave device.
int | twi_probe (volatile avr32_twi_t *twi, char chip_addr)
| Test if a chip answers for a given twi address.
int | twi_slave_init (volatile avr32_twi_t *twi, const twi_options_t *opt, const twi_slave_fct_t *slave_fct)
| Initialize the twi slave module.

## Define Documentation

#define TWI_ARBITRATION_LOST -2

Definition at line 57 of file twi.h.

#define TWI_INVALID_ARGUMENT -1

Definition at line 56 of file twi.h.

Referenced by twi_master_read(), and twi_master_write().

#define TWI_NO_CHIP_FOUND -3

Definition at line 58 of file twi.h.

#define TWI_RECEIVE_NACK -5

Definition at line 60 of file twi.h.

Referenced by twi_master_read(), and twi_master_write().

#define TWI_RECEIVE_OVERRUN -4

Definition at line 59 of file twi.h.

#define TWI_SEND_NACK -7

Definition at line 62 of file twi.h.

#define TWI_SEND_OVERRUN -6

Definition at line 61 of file twi.h.

#define TWI_SUCCESS 0

Definition at line 55 of file twi.h.

Referenced by main(), twi_master_read(), twi_master_write(), twi_set_speed(), and twi_slave_init().

## Function Documentation

void twi_disable_interrupt | ( | volatile avr32_twi_t * | twi | ) |

Disable all TWI interrupts.

Parameters:

  | twi | Base address of the TWI (i.e. &AVR32_TWI).

Definition at line 347 of file twi.c.

Referenced by twi_master_inst1_interrupt_handler().

    00348 {
    00349   Bool global_interrupt_enabled = Is_global_interrupt_enabled();
    00350
    00351   if (global_interrupt_enabled) Disable_global_interrupt();
    00352   twi->idr = ~0UL;
    00353   twi->sr;
    00354   if (global_interrupt_enabled) Enable_global_interrupt();
    00355 }

int twi_master_init | ( | volatile avr32_twi_t * | twi,
|  | const twi_options_t * | opt |
| ) |  |  |

Initialize the twi master module.

Parameters:

  | twi | Base address of the TWI (i.e. &AVR32_TWI).
  | *opt | Options for initializing the twi module (see twi_options_t)

Definition at line 258 of file twi.c.

References twi_options_t::chip, twi_options_t::pba_hz, twi_options_t::speed, twi_master_inst1_interrupt_handler(), twi_probe(), and twi_set_speed().

Referenced by main().

    00259 {
    00260   Bool global_interrupt_enabled = Is_global_interrupt_enabled();
    00261   int status;
    00262
    00263   // Disable TWI interrupts
    00264   if (global_interrupt_enabled) Disable_global_interrupt();
    00265   twi->idr = ~0UL;
    00266   twi->sr;
    00267
    00268   // Reset TWI
    00269   twi->cr = AVR32_TWI_CR_SWRST_MASK;
    00270   if (global_interrupt_enabled) Enable_global_interrupt();
    00271
    00272   // Dummy read in SR
    00273   status = twi->sr;
    00274
    00275   // Disable all interrupts
    00276   Disable_global_interrupt();
    00277
    00278   // Register TWI handler on level 2
    00279   INTC_register_interrupt( &twi_master_inst1_interrupt_handler, AVR32_TWI_IRQ, AVR32_INTC_INT1);
    00280
    00281   // Enable all interrupts
    00282   Enable_global_interrupt();
    00283
    00284   // Select the speed
    00285   twi_set_speed(twi, opt->speed, opt->pba_hz);
    00286
    00287   // Probe the component
    00288   status = twi_probe(twi, opt->chip);
    00289
    00290   return status;
    00291 }

int twi_master_read | ( | volatile avr32_twi_t * | twi,
|  | const twi_package_t * | package |
| ) |  |  |

Read multiple bytes from a TWI compatible slave device.

Parameters:

  | twi | Base address of the TWI (i.e. &AVR32_TWI).
  | package | Package information and data (see twi_package_t)

Returns:
  TWI_SUCCESS if all bytes were read, error code otherwhise

Definition at line 378 of file twi.c.

References twi_package_t::addr, twi_package_t::addr_length, twi_package_t::buffer, twi_package_t::chip, twi_package_t::length, TWI_INVALID_ARGUMENT, twi_it_mask, twi_nack, TWI_RECEIVE_NACK, twi_rx_data, twi_rx_nb_bytes, and TWI_SUCCESS.

Referenced by main().

    00379 {
    00380   // check argument
    00381   if (package->length == 0)
    00382   {
    00383     return TWI_INVALID_ARGUMENT;
    00384   }
    00385
    00386   twi_nack = FALSE;
    00387
    00388   // set read mode, slave address and 3 internal address byte length
    00389   twi->mmr = (package->chip << AVR32_TWI_MMR_DADR_OFFSET) |
    00390              ((package->addr_length << AVR32_TWI_MMR_IADRSZ_OFFSET) & AVR32_TWI_MMR_IADRSZ_MASK) |
    00391              (1 << AVR32_TWI_MMR_MREAD_OFFSET);
    00392
    00393   // set internal address for remote chip
    00394   twi->iadr = package->addr;
    00395
    00396   // get a pointer to applicative data
    00397   twi_rx_data = package->buffer;
    00398
    00399   // get a copy of nb bytes to read
    00400   twi_rx_nb_bytes = package->length;
    00401
    00402   // Enable master transfer
    00403   twi->cr =  AVR32_TWI_CR_MSEN_MASK;
    00404
    00405   // Send start condition
    00406   twi->cr = AVR32_TWI_START_MASK;
    00407
    00408   // only one byte to receive
    00409   if(twi_rx_nb_bytes == 1)
    00410   {
    00411     // set stop bit
    00412     twi->cr = AVR32_TWI_STOP_MASK;
    00413   }
    00414
    00415   // mask NACK and RXRDY interrupts
    00416   twi_it_mask = AVR32_TWI_IER_NACK_MASK | AVR32_TWI_IER_RXRDY_MASK;
    00417
    00418   // update IMR through IER
    00419   twi->ier = twi_it_mask;
    00420
    00421   // get data
    00422   while (!twi_nack && twi_rx_nb_bytes);
    00423
    00424   // Disable master transfer
    00425   twi->cr =  AVR32_TWI_CR_MSDIS_MASK;
    00426
    00427   if( twi_nack )
    00428     return TWI_RECEIVE_NACK;
    00429
    00430   return TWI_SUCCESS;
    00431 }

int twi_master_write | ( | volatile avr32_twi_t * | twi,
|  | const twi_package_t * | package |
| ) |  |  |

Write multiple bytes to a TWI compatible slave device.

Parameters:

  | twi | Base address of the TWI (i.e. &AVR32_TWI).
  | *package | Package information and data (see twi_package_t)

Returns:
  TWI_SUCCESS if all bytes were written, error code otherwhise

Definition at line 434 of file twi.c.

References twi_package_t::addr, twi_package_t::addr_length, twi_package_t::buffer, twi_package_t::chip, twi_package_t::length, twi_inst1, TWI_INVALID_ARGUMENT, twi_it_mask, twi_nack, TWI_RECEIVE_NACK, TWI_SUCCESS, twi_tx_data, and twi_tx_nb_bytes.

Referenced by main(), and twi_probe().

    00435 {
    00436   // No data to send
    00437   if (package->length == 0)
    00438   {
    00439     return TWI_INVALID_ARGUMENT;
    00440   }
    00441
    00442   twi_nack = FALSE;
    00443
    00444   // Enable master transfer, disable slave
    00445   twi->cr =   AVR32_TWI_CR_MSEN_MASK
    00446 #ifndef AVR32_TWI_180_H_INCLUDED
    00447             | AVR32_TWI_CR_SVDIS_MASK
    00448 #endif
    00449             ;
    00450
    00451   // set write mode, slave address and 3 internal address byte length
    00452   twi->mmr = (0 << AVR32_TWI_MMR_MREAD_OFFSET) |
    00453              (package->chip << AVR32_TWI_MMR_DADR_OFFSET) |
    00454              ((package->addr_length << AVR32_TWI_MMR_IADRSZ_OFFSET) & AVR32_TWI_MMR_IADRSZ_MASK);
    00455
    00456   // set internal address for remote chip
    00457   twi->iadr = package->addr;
    00458
    00459   // get a pointer to applicative data
    00460   twi_tx_data = package->buffer;
    00461
    00462   // get a copy of nb bytes to write
    00463   twi_tx_nb_bytes = package->length;
    00464
    00465   // put the first byte in the Transmit Holding Register
    00466   twi_inst1->thr = *twi_tx_data++;
    00467
    00468   // mask NACK and TXRDY interrupts
    00469   twi_it_mask = AVR32_TWI_IER_NACK_MASK | AVR32_TWI_IER_TXRDY_MASK;
    00470
    00471   // update IMR through IER
    00472   twi->ier = twi_it_mask;
    00473
    00474   // send data
    00475   while (!twi_nack && twi_tx_nb_bytes);
    00476
    00477   // Disable master transfer
    00478   twi->cr =  AVR32_TWI_CR_MSDIS_MASK;
    00479
    00480   if( twi_nack )
    00481     return TWI_RECEIVE_NACK;
    00482
    00483   return TWI_SUCCESS;
    00484 }

int twi_probe | ( | volatile avr32_twi_t * | twi,
|  | char | chip_addr |
| ) |  |  |

Test if a chip answers for a given twi address.

Parameters:

  | twi | Base address of the TWI (i.e. &AVR32_TWI).
  | chip_addr | Address of the chip which is searched for

Returns:
  TWI_SUCCESS if a chip was found, error code otherwhise

Definition at line 358 of file twi.c.

References twi_package_t::addr, twi_package_t::addr_length, twi_package_t::buffer, twi_package_t::chip, twi_package_t::length, and twi_master_write().

Referenced by twi_master_init().

    00359 {
    00360   twi_package_t package;
    00361   char data[1] = {0};
    00362
    00363   // data to send
    00364   package.buffer = data;
    00365   // chip address
    00366   package.chip = chip_addr;
    00367   // frame length
    00368   package.length = 1;
    00369   // address length
    00370   package.addr_length = 0;
    00371   // internal chip address
    00372   package.addr = 0;
    00373   // perform a master write access
    00374   return (twi_master_write(twi, &package));
    00375 }

int twi_slave_init | ( | volatile avr32_twi_t * | twi,
|  | const twi_options_t * | opt,
|  | const twi_slave_fct_t * | slave_fct |
| ) |  |  |

Initialize the twi slave module.

Parameters:

  | twi | Base address of the TWI (i.e. &AVR32_TWI).
  | *opt | Options for initializing the twi module (see twi_options_t)
  | *slave_fct | Pointer on application fonctions

Definition at line 296 of file twi.c.

References twi_options_t::chip, twi_options_t::pba_hz, twi_options_t::speed, twi_it_mask, twi_set_speed(), twi_slave_inst1_interrupt_handler(), and TWI_SUCCESS.

    00297 {
    00298   Bool global_interrupt_enabled = Is_global_interrupt_enabled();
    00299
    00300   // Disable TWI interrupts
    00301   if (global_interrupt_enabled) Disable_global_interrupt();
    00302   twi->idr = ~0UL;
    00303   twi->sr;
    00304
    00305   // Reset TWI
    00306   twi->cr = AVR32_TWI_CR_SWRST_MASK;
    00307
    00308   if (global_interrupt_enabled) Enable_global_interrupt();
    00309
    00310   // Dummy read in SR
    00311   twi->sr;
    00312
    00313   // Disable all interrupts
    00314   Disable_global_interrupt();
    00315
    00316   // Register TWI handler on level 2
    00317   INTC_register_interrupt( &twi_slave_inst1_interrupt_handler, AVR32_TWI_IRQ, AVR32_INTC_INT1);
    00318
    00319   // Enable all interrupts
    00320   Enable_global_interrupt();
    00321
    00322   // Select the speed
    00323   twi_set_speed(twi, opt->speed, opt->pba_hz);
    00324
    00325   //** Link reception routine
    00326
    00327   // Disable master transfer, ensable slave
    00328   twi->cr =  AVR32_TWI_CR_MSDIS_MASK|AVR32_TWI_CR_SVEN_MASK;
    00329
    00330   // Set slave address
    00331   twi->smr = (opt->chip << AVR32_TWI_SMR_SADR_OFFSET);
    00332
    00333   // get a pointer to applicative routines
    00334   twi_slave_fct = *slave_fct;
    00335
    00336   // Slave Access Interrupt Enable
    00337   twi_it_mask = AVR32_TWI_IER_SVACC_MASK;
    00338   twi->ier = twi_it_mask;
    00339
    00340   // Everything went ok
    00341   return TWI_SUCCESS;
    00342 }