rt-thread/bsp/samd21/sam_d2x_asflib/common/services/twi/twi_master.h

/**
 * \file
 *
 * \brief TWI Master Mode management
 *
 * Copyright (c) 2010-2015 Atmel Corporation. All rights reserved.
 *
 * \asf_license_start
 *
 * \page License
 *
 * 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.
 *
 * 4. This software may only be redistributed and used in connection with an
 *    Atmel microcontroller product.
 *
 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT 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.
 *
 * \asf_license_stop
 *
 */
/*
 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
 */
#ifndef TWI_MASTER_H_INCLUDED
#define TWI_MASTER_H_INCLUDED

#include <compiler.h>

#if (SAM4L)
# include "sam_twim/twi_master.h"
#elif (SAM3S || SAM3U || SAM3N || SAM3XA || SAM4S || SAM4E || SAM4N || SAM4C || SAMG || SAM4CP || SAM4CM)
# include "sam_twi/twi_master.h"
#elif XMEGA
# include "xmega_twi/twi_master.h"
#elif MEGA_RF
# include "megarf_twi/twi_master.h"
#elif UC3
# if (defined AVR32_TWI)
# include "uc3_twi/twi_master.h"
# else
# include "uc3_twim/twi_master.h"
# endif
#else
# error Unsupported chip type
#endif

/**
 *
 * \defgroup twi_group Two Wire-interface(TWI)
 *
 * This is the common API for TWIs. Additional features are available
 * in the documentation of the specific modules.
 *
 * See \ref twi_quickstart.
 *
 * \section twi_group_platform Platform Dependencies
 *
 * The TWI API is partially chip- or platform-specific. While all
 * platforms provide mostly the same functionality, there are some
 * variations around how different bus types and clock tree structures
 * are handled.
 *
 * The following functions are available on all platforms, but there may
 * be variations in the function signature (i.e. parameters) and
 * behaviour. These functions are typically called by platform-specific
 * parts of drivers, and applications that aren't intended to be
 * portable:
 *   - Master TWI Module initialization
 *   \code status_code_t twi_master_setup(*twi_module_pointer, twi_master_options_t *opt) \endcode
 *   - Enables TWI Module
 *   \code void twi_master_enable(*twi_module_pointer) \endcode
 *   - Disables TWI Module
 *   \code void twi_master_disable(*twi_module_pointer) \endcode
 *   - Read data from a slave device
 *   \code status_code_t twi_master_read(*twi_module_pointer, twi_package_t *package) \endcode
 *   - Write data from to a slave device
 *   \code status_code_t twi_master_write(*twi_module_pointer, twi_package_t *package) \endcode
 *
 * @{
 */

/**
 * \typedef twi_master_t
 * This type can be used independently to refer to TWI master module for the
 * architecture used. It refers to the correct type definition for the
 * architecture, ie. TWI_t* for XMEGA or avr32_twim_t* for UC3
 */

//! @}


/**
 * \page twi_quickstart Quickstart guide for Common service TWI
 *
 * This is the quickstart guide for the \ref twi_group "Common service TWI",
 * with step-by-step instructions on how to configure and use the driver in a
 * selection of use cases.
 *
 * The use cases contain several code fragments. The code fragments in the
 * steps for setup can be copied into a custom initialization function, while
 * the steps for usage can be copied into, e.g., the main application function.
 *
 * \section twi_basic_use_case Basic use case
 * In the most basic use case, the TWI module is configured for
 * - Master operation
 * - addressing one slave device of the bus at address 0x50
 * - TWI clock of 50kHz
 * - polled read/write handling
 *
 * \section twi_basic_use_case_setup Setup steps
 * \subsection twi_basic_use_case_setup_code Example code
 * Add to your application C-file:
 * \code
	  void twi_init(void)
	  {
	    twi_master_options_t opt = {
	        .speed = 50000,
	        .chip  = 0x50
	    };

	    twi_master_setup(&TWIM0, &opt);
	  }
\endcode
 *
 * \subsection twi_basic_use_case_setup_flow Workflow
 * -# Ensure that board_init() has configured selected I/Os for TWI function.
 * -# Ensure that \ref conf_twim.h is present for the driver.
 *   - \note This file is only for the driver and should not be included by the
 * user.
 * -# Define and initialize config structs for TWI module in your TWI initialization
 * function:
 *   - \code
	twi_master_options_t opt = {
	  .speed = 50000,
	  .chip  = 0x50
	}; \endcode
 *   - field \ref speed sets the baudrate of the TWI bus
 *   - field \ref chip sets the address of the slave device you want to communicate with
 * -# Call twi_master_setup and optionally check its return code
 *   - \note The config structs can be reused for other TWI modules
 * after this step. Simply reconfigure and write to others modules.
 *
 * \section twi_basic_use_case_usage Usage steps
 * \subsection twi_basic_use_case_usage_code_writing Example code : Writing to a slave device
 * Use in application C-file:
 * \code
	  const uint8_t test_pattern[] = {0x55,0xA5,0x5A,0x77,0x99};

	  twi_package_t packet_write = {
	    .addr         = EEPROM_MEM_ADDR,      // TWI slave memory address data
	    .addr_length  = sizeof (uint16_t),    // TWI slave memory address data size
	    .chip         = EEPROM_BUS_ADDR,      // TWI slave bus address
	    .buffer       = (void *)test_pattern, // transfer data source buffer
	    .length       = sizeof(test_pattern)  // transfer data size (bytes)
	  };

	  while (twi_master_write(&TWIM0, &packet_write) != TWI_SUCCESS);
\endcode
 *
 * \subsection twi_basic_use_case_usage_flow Workflow
 * -# Prepare the data you want to send to the slave device:
 *   - \code const uint8_t test_pattern[] = {0x55,0xA5,0x5A,0x77,0x99}; \endcode
 * -# Prepare a twi_package_t structure
 *   \code twi_package_t packet_write; \endcode
 * Fill all the fields of the structure :
 *  - addr is the address in the slave device
 *  - addr_length is the size of the address in the slave (support for large TWI memory devices)
 *  - chip sets the 7 bit address of the slave device you want to communicate with
 *  - buffer is a pointer on the data to write to slave
 *  - length is the number of data to write
 *
 * -# Finally, call twi_master_write \code twi_master_write(&TWIM0, &packet_write); \endcode
 * and optionally check its return value for TWI_SUCCESS.
 * \subsection twi_basic_use_case_usage_code_reading Example code : Reading from a slave device
 * Use in application C-file:
 * \code
	   uint8_t data_received[10];

	   twi_package_t packet_read = {
	     .addr         = EEPROM_MEM_ADDR,      // TWI slave memory address data
	     .addr_length  = sizeof (uint16_t),    // TWI slave memory address data size
	     .chip         = EEPROM_BUS_ADDR,      // TWI slave bus address
	     .buffer       = data_received,        // transfer data destination buffer
	     .length       = 10                    // transfer data size (bytes)
	   };
	   // Perform a multi-byte read access then check the result.
	   if(twi_master_read(&TWIM0, &packet_read) == TWI_SUCCESS){
	     //Check read content
	     if(data_received[0]==0x55)
	       do_something();
	   }
\endcode
 *
 * \subsection twi_basic_use_case_usage_flow Workflow
 * -# Prepare a data buffer that will receive the data from the slave device:
 *   \code uint8_t data_received[10]; \endcode
 * -# Prepare a twi_package_t structure
 *   \code twi_package_t packet_read; \endcode
 * Fill all the fields of the structure :
 *  - addr is the address in the slave device
 *  - addr_length is the size of the address in the slave (support for large TWI memory devices)
 *  - chip sets the 7 bit address of the slave device you want to communicate with
 *  - buffer is a pointer on the data buffer that will receive the data from the slave device
 *  - length is the number of data to read
 *
 * -# Finally, call twi_master_read \code twi_master_read(&TWIM0, &packet_read); \endcode
 * and optionally check its return value for TWI_SUCCESS.
 * the data read from the device are now in data_received.
 */


#endif /* TWI_MASTER_H_INCLUDED */