git.sur5r.net Git - freertos/blob - Demo/CORTEX_A2F200_SoftConsole/MicroSemi_Code/drivers/I2C/i2c.h

   1 /*******************************************************************************\r
   2  * (c) Copyright 2007-2008 Actel Corporation.  All rights reserved.\r
   3  *\r
   4  * SmartFusion microcontroller subsystem I2C bare metal software driver public\r
   5  * API.\r
   6  *\r
   7  * SVN $Revision: 2150 $\r
   8  * SVN $Date: 2010-02-11 14:39:24 +0000 (Thu, 11 Feb 2010) $\r
   9  */\r
  10 /*=========================================================================*//**\r
  11   @mainpage SmartFusion MSS I2C Bare Metal Driver.\r
  12 \r
  13   @section intro_sec Introduction\r
  14   The SmartFusion™ microcontroller subsystem (MSS) includes two I2C peripherals\r
  15   for serial communication. This driver provides a set of functions for\r
  16   controlling the MSS I2Cs as part of a bare metal system where no operating\r
  17   system is available. These drivers can be adapted for use as part of an\r
  18   operating system, but the implementation of the adaptation layer between this\r
  19   driver and the operating system's driver model is outside the scope of this\r
  20   driver.\r
  21 \r
  22   @section hw_dependencies Hardware Flow Dependencies\r
  23   The configuration of all features of the MSS I2Cs is covered by this driver\r
  24   with the exception of the SmartFusion IOMUX configuration. SmartFusion allows\r
  25   multiple non-concurrent uses of some external pins through IOMUX configuration.\r
  26   This feature allows optimization of external pin usage by assigning external\r
  27   pins for use by either the microcontroller subsystem or the FPGA fabric. The\r
  28   MSS I2Cs serial signals are routed through IOMUXes to the SmartFusion device\r
  29   external pins. These IOMUXes are automatically configured correctly by the MSS\r
  30   configurator tool in the hardware flow when the MSS I2Cs are enabled in that\r
  31   tool. You must ensure that the MSS I2Cs are enabled by the MSS configurator\r
  32   tool in the hardware flow; otherwise the serial inputs and outputs will not be\r
  33   connected to the chip's external pins. For more information on IOMUX, refer to\r
  34   the IOMUX section of the SmartFusion Datasheet.\r
  35   The base address, register addresses and interrupt number assignment for the\r
  36   MSS I2C blocks are defined as constants in the SmartFusion CMSIS-PAL. You must\r
  37   ensure that the SmartFusion CMSIS-PAL is either included in the software tool\r
  38   chain used to build your project or is included in your project.\r
  39 \r
  40   @section theory_op Theory of Operation\r
  41   The MSS I2C driver functions are grouped into the following categories:\r
  42     • Initialization and configuration functions\r
  43     • Interrupt control\r
  44     • I2C master operations – functions to handle write, read and write-read transactions\r
  45     • I2C slave operations – functions to handle write, read and write-read transactions\r
  46 \r
  47   Initialization and Configuration\r
  48     The MSS I2C driver is initialized through a call to the MSS_I2C_init()\r
  49     function. This function takes the MSS I2C's configuration as parameters. The\r
  50     MSS_I2C_init() function must be called before any other MSS I2C driver\r
  51     functions can be called. The first parameter of the MSS_I2C_init() function\r
  52     is a pointer to one of two global data structures used by the driver to\r
  53     store state information for each MSS I2C. A pointer to these data structures\r
  54     is also used as first parameter to any of the driver functions to identify\r
  55     which MSS I2C will be used by the called function. The names of these two\r
  56     data structures are g_mss_i2c0 and g_mss_i2c1. Therefore any call to an MSS\r
  57     I2C driver function should be of the form MSS_I2C_function_name( &g_mss_i2c0, ... )\r
  58     or MSS_I2C_function_name( &g_mss_i2c1, ... ).\r
  59     The MSS_I2C_init() function call for each MSS I2C also takes the I2C serial\r
  60     address assigned to the MSS I2C and the serial clock divider to be used to\r
  61     generate its I2C clock as configuration parameters.\r
  62 \r
  63   Interrupt Control\r
  64     The MSS I2C driver is interrupt driven and it enables and disables the\r
  65     generation of interrupts by MSS I2C at various times when it is operating.\r
  66     The driver automatically handles MSS I2C interrupts internally, including\r
  67     enabling disabling and clearing MSS I2C interrupts in the Cortex-M3\r
  68     interrupt controller when required.\r
  69     The function MSS_I2C_register_write_handler() is used to register a write\r
  70     handler function with the MSS I2C driver that it will call on completion of\r
  71     an I2C write transaction by the MSS I2C slave. It is your responsibility to\r
  72     create and register the implementation of this handler function that will\r
  73     process or trigger the processing of the received data.\r
  74   Transaction Types\r
  75     The MSS I2C driver is designed to handle three types of I2C transaction:\r
  76       • Write transactions\r
  77       • Read transactions\r
  78       • Write-read transactions\r
  79 \r
  80     Write transaction\r
  81       The master I2C device initiates a write transaction by sending a START bit\r
  82       as soon as the bus becomes free. The START bit is followed by the 7-bit\r
  83       serial address of the target slave device followed by the read/write bit\r
  84       indicating the direction of the transaction. The slave acknowledges receipt\r
  85       of it’s address with an acknowledge bit. The master sends data one byte at\r
  86       a time to the slave, which must acknowledge receipt of each byte for the\r
  87       next byte to be sent. The master sends a STOP bit to complete the transaction.\r
  88       The slave can abort the transaction by replying with a non-acknowledge bit\r
  89       instead of an acknowledge.\r
  90       The application programmer can choose not to send a STOP bit at the end of\r
  91       the transaction causing the next transaction to begin with a repeated START bit.\r
  92 \r
  93     Read transaction\r
  94       The master I2C device initiates a read transaction by sending a START bit\r
  95       as soon as the bus becomes free. The START bit is followed by the 7-bit\r
  96       serial address of the target slave device followed by the read/write bit\r
  97       indicating the direction of the transaction. The slave acknowledges receipt\r
  98       of it’s slave address with an acknowledge bit. The slave sends data one byte\r
  99       at a time to the master, which must acknowledge receipt of each byte for the\r
 100       next byte to be sent. The master sends a non-acknowledge bit following the\r
 101       last byte it wishes to read followed by a STOP bit.\r
 102       The application programmer can choose not to send a STOP bit at the end of\r
 103       the transaction causing the next transaction to begin with a repeated START bit.\r
 104 \r
 105     Write-read transaction\r
 106       The write-read transaction is a combination of a write transaction\r
 107       immediately followed by a read transaction. There is no STOP bit between\r
 108       the write and read phases of a write-read transaction. A repeated START\r
 109       bit is sent between the write and read phases.\r
 110       The write-read transaction is typically used to send a command or offset\r
 111       in the write transaction specifying the logical data to be transferred\r
 112       during the read phase.\r
 113       The application programmer can choose not to send a STOP bit at the end of\r
 114       the transaction causing the next transaction to begin with a repeated START bit.\r
 115 \r
 116   Master Operations\r
 117     The application can use the MSS_I2C_write(), MSS_I2C_read() and MSS_I2C_write_read()\r
 118     functions to initiate an I2C bus transaction. The application can then wait\r
 119     for the transaction to complete using the MSS_I2C_wait_complete() function\r
 120     or poll the status of the I2C transaction using the MSS_I2C_get_status()\r
 121     function until it returns a value different from MSS_I2C_IN_PROGRESS.\r
 122 \r
 123   Slave Operations\r
 124     The configuration of the MSS I2C driver to operate as an I2C slave requires\r
 125     the use of the following functions:\r
 126       • MSS_I2C_set_slave_tx_buffer()\r
 127       • MSS_I2C_set_slave_rx_buffer()\r
 128       • MSS_I2C_set_slave_mem_offset_length()\r
 129       • MSS_I2C_register_write_handler()\r
 130       • MSS_I2C_enable_slave_rx()\r
 131     Use of all functions is not required if the slave I2C does not need to support\r
 132     all types of I2C read transactions. The subsequent sections list the functions\r
 133     that must be used to support each transaction type.\r
 134 \r
 135     Responding to read transactions\r
 136       The following functions are used to configure the MSS I2C driver to respond\r
 137       to I2C read transactions:\r
 138         • MSS_I2C_set_slave_tx_buffer()\r
 139         • MSS_I2C_enable_slave_rx()\r
 140       The function MSS_I2C_set_slave_tx_buffer() specifies the data buffer that\r
 141       will be transmitted when the I2C slave is the target of an I2C read\r
 142       transaction. It is then up to the application to manage the content of that\r
 143       buffer to control the data that will be transmitted to the I2C master as a\r
 144       result of the read transaction.\r
 145       The function MSS_I2C_enable_slave_rx() enables the MSS I2C hardware instance\r
 146       to respond to I2C transactions. It must be called after the MSS I2C driver\r
 147       has been configured to respond to the required transaction types.\r
 148 \r
 149     Responding to write transactions\r
 150       The following functions are used to configure the MSS I2C driver to respond\r
 151       to I2C write transactions:\r
 152         • MSS_I2C_set_slave_rx_buffer()\r
 153         • MSS_I2C_register_write_handler()\r
 154         • MSS_I2C_enable_slave_rx()\r
 155       The function MSS_I2C_set_slave_rx_buffer() specifies the data buffer that\r
 156       will be used to store the data received by the I2C slave when it is the\r
 157       target an I2C  write transaction.\r
 158       The function MSS_I2C_register_write_handler() specifies the handler function\r
 159       that must be called on completion of the I2C write transaction. It is this\r
 160       handler function that will process or trigger the processing of the received\r
 161       data.\r
 162       The function MSS_I2C_enable_slave_rx() enables the MSS I2C hardware instance\r
 163       to respond to I2C transactions. It must be called after the MSS I2C driver\r
 164       has been configured to respond to the required transaction types.\r
 165 \r
 166     Responding to write-read transactions\r
 167       The following functions are used to configure the MSS I2C driver to respond\r
 168       to write-read transactions:\r
 169         • MSS_I2C_set_slave_tx_buffer()\r
 170         • MSS_I2C_set_slave_rx_buffer()\r
 171         • MSS_I2C_set_slave_mem_offset_length()\r
 172         • MSS_I2C_enable_slave_rx()\r
 173       The function MSS_I2C_set_slave_mem_offset_length() specifies the number of\r
 174       bytes expected by the I2C slave during the write phase of the write-read\r
 175       transaction.\r
 176       The function MSS_I2C_set_slave_tx_buffer() specifies the data that will be\r
 177       transmitted to the I2C master during the read phase of the write-read\r
 178       transaction. The value received by the I2C slave during the write phase of\r
 179       the transaction will be used as an index into the transmit buffer specified\r
 180       by this function to decide which part of the transmit buffer will be\r
 181       transmitted to the I2C master as part of the read phase of the write-read\r
 182       transaction.\r
 183       The function MSS_I2C_set_slave_rx_buffer() specifies the data buffer that\r
 184       will be used to store the data received by the I2C slave during the write\r
 185       phase of the write-read transaction. This buffer must be at least large\r
 186       enough to accommodate the number of bytes specified through the\r
 187       MSS_I2C_set_slave_mem_offset_length() function.\r
 188       The function MSS_I2C_enable_slave_rx() enables the MSS I2C hardware\r
 189       instance to respond to I2C transactions. It must be called after the MSS\r
 190       I2C driver has been configured to respond to the required transaction types.\r
 191  *//*=========================================================================*/\r
 192 #ifndef I2C_H_\r
 193 #define I2C_H_\r
 194 \r
 195 #include "../../CMSIS/a2fxxxm3.h"\r
 196 \r
 197 #ifdef __cplusplus\r
 198 extern "C" {\r
 199 #endif\r
 200 \r
 201 /*-------------------------------------------------------------------------*//**\r
 202   The mss_i2c_clock_divider_t type is used to specify the divider to be applied\r
 203   to the MSS I2C BCLK signal in order to generate the I2C clock.\r
 204  */\r
 205 typedef enum mss_i2c_clock_divider {\r
 206     MSS_I2C_PCLK_DIV_256 = 0,\r
 207     MSS_I2C_PCLK_DIV_224,\r
 208     MSS_I2C_PCLK_DIV_192,\r
 209     MSS_I2C_PCLK_DIV_160,\r
 210     MSS_I2C_PCLK_DIV_960,\r
 211     MSS_I2C_PCLK_DIV_120,\r
 212     MSS_I2C_PCLK_DIV_60,\r
 213     MSS_I2C_BCLK_DIV_8\r
 214 } mss_i2c_clock_divider_t;\r
 215 \r
 216 /*-------------------------------------------------------------------------*//**\r
 217   The MSS_I2C_RELEASE_BUS constant is used to specify the options parameter to\r
 218   functions MSS_I2C_read(), MSS_I2C_write() and MSS_I2C_write_read() to indicate\r
 219   that a STOP bit must be generated at the end of the I2C transaction to release\r
 220   the bus.\r
 221  */\r
 222 #define MSS_I2C_RELEASE_BUS     0x00\r
 223 \r
 224 /*-------------------------------------------------------------------------*//**\r
 225   The MSS_I2C_HOLD_BUS constant is used to specify the options parameter to\r
 226   functions MSS_I2C_read(), MSS_I2C_write() and MSS_I2C_write_read() to indicate\r
 227   that a STOP bit must not be generated at the end of the I2C transaction in\r
 228   order to retain the bus ownership. This will cause the next transaction to\r
 229   begin with a repeated START bit and no STOP bit between the transactions.\r
 230  */\r
 231 #define MSS_I2C_HOLD_BUS        0x01\r
 232 \r
 233 /*-------------------------------------------------------------------------*//**\r
 234   The mss_i2c_status_t type is used to report the status of I2C transactions.\r
 235  */\r
 236 typedef enum mss_i2c_status\r
 237 {\r
 238     MSS_I2C_SUCCESS = 0,\r
 239     MSS_I2C_IN_PROGRESS,\r
 240     MSS_I2C_FAILED\r
 241 } mss_i2c_status_t;\r
 242 \r
 243 /*-------------------------------------------------------------------------*//**\r
 244   The mss_i2c_slave_handler_ret_t type is used by slave write handler functions\r
 245   to indicate whether the received data buffer should be released or not.\r
 246  */\r
 247 typedef enum mss_i2c_slave_handler_ret {\r
 248     MSS_I2C_REENABLE_SLAVE_RX = 0,\r
 249     MSS_I2C_PAUSE_SLAVE_RX = 1\r
 250 } mss_i2c_slave_handler_ret_t;\r
 251 \r
 252 /*-------------------------------------------------------------------------*//**\r
 253   Slave write handler functions prototype.\r
 254   ------------------------------------------------------------------------------\r
 255   This defines the function prototype that must be followed by MSS I2C slave\r
 256   write handler functions. These functions are registered with the MSS I2C driver\r
 257   through the MSS_I2C_register_write_handler() function.\r
 258 \r
 259   Declaring and Implementing Slave Write Handler Functions:\r
 260     Slave write handler functions should follow the following prototype:\r
 261     mss_i2c_slave_handler_ret_t write_handler( uint8_t * data, uint16_t size );\r
 262 \r
 263     The data parameter is a pointer to a buffer (received data buffer) holding\r
 264     the data written to the MSS I2C slave.\r
 265     The size parameter is the number of bytes held in the received data buffer.\r
 266     Handler functions must return one of the following values:\r
 267         • MSS_I2C_REENABLE_SLAVE_RX\r
 268         • MSS_I2C_PAUSE_SLAVE_RX.\r
 269     If the handler function returns MSS_I2C_REENABLE_SLAVE_RX, the driver will\r
 270     release the received data buffer and allow further I2C write transactions to\r
 271     the MSS I2C slave to take place.\r
 272     If the handler function returns MSS_I2C_PAUSE_SLAVE_RX, the MSS I2C slave\r
 273     will respond to subsequent write requests with a non-acknowledge bit (NACK),\r
 274     until the received data buffer content has been processed by some other part\r
 275     of the software application.\r
 276     A call to MSS_I2C_enable_slave_rx() is required at some point after\r
 277     returning MSS_I2C_PAUSE_SLAVE_RX in order to release the received data\r
 278     buffer so it can be used to store data received by subsequent I2C write\r
 279     transactions.\r
 280  */\r
 281 typedef mss_i2c_slave_handler_ret_t (*mss_i2c_slave_wr_handler_t)( uint8_t *, uint16_t );\r
 282 \r
 283 /*-------------------------------------------------------------------------*//**\r
 284   mss_i2c_instance_t\r
 285   ------------------------------------------------------------------------------\r
 286   There is one instance of this structure for each of the microcontroller\r
 287   subsystem's I2Cs. Instances of this structure are used to identify a specific\r
 288   I2C. A pointer to an instance of the mss_i2c_instance_t structure is passed as\r
 289   the first parameter to MSS I2C driver functions to identify which I2C should\r
 290   perform the requested operation.\r
 291  */\r
 292 typedef struct mss_i2c_instance\r
 293 {\r
 294         uint_fast8_t ser_address;\r
 295         /* Transmit related info:*/\r
 296         uint_fast8_t target_addr;\r
 297 \r
 298         /* Current transaction type (WRITE, READ, RANDOM_READ)*/\r
 299         uint8_t transaction;\r
 300 \r
 301         uint_fast16_t random_read_addr;\r
 302 \r
 303     uint8_t options;\r
 304 \r
 305         /* I2C hardware instance identification */\r
 306     IRQn_Type  irqn;\r
 307     I2C_TypeDef * hw_reg;\r
 308     I2C_BitBand_TypeDef * hw_reg_bit;\r
 309 \r
 310         /* TX INFO: */\r
 311         const uint8_t * tx_buffer;\r
 312         uint_fast16_t tx_size;\r
 313         uint_fast16_t tx_idx;\r
 314         uint_fast8_t dir;\r
 315 \r
 316         /* RX INFO: */\r
 317         uint8_t * rx_buffer;\r
 318         uint_fast16_t rx_size;\r
 319         uint_fast16_t rx_idx;\r
 320 \r
 321         /* status variable: */\r
 322     volatile mss_i2c_status_t status;\r
 323 \r
 324         /* Slave data: */\r
 325         uint_fast8_t slave_mem_offset_length;\r
 326         mss_i2c_slave_wr_handler_t slave_write_handler;\r
 327 \r
 328 } mss_i2c_instance_t;\r
 329 \r
 330 /*-------------------------------------------------------------------------*//**\r
 331   This instance of mss_i2c_instance_t holds all data related to the operations\r
 332   performed by MSS I2C 0. A pointer to g_mss_i2c0 is passed as the first\r
 333   parameter to MSS I2C driver functions to indicate that MSS I2C 0 should\r
 334   perform the requested operation.\r
 335  */\r
 336 extern mss_i2c_instance_t g_mss_i2c0;\r
 337 \r
 338 /*-------------------------------------------------------------------------*//**\r
 339   This instance of mss_i2c_instance_t holds all data related to the operations\r
 340   performed by MSS I2C 1. A pointer to g_mss_i2c1 is passed as the first\r
 341   parameter to MSS I2C driver functions to indicate that MSS I2C 1 should\r
 342   perform the requested operation.\r
 343  */\r
 344 extern mss_i2c_instance_t g_mss_i2c1;\r
 345 \r
 346 /*-------------------------------------------------------------------------*//**\r
 347   MSS I2C initialisation routine.\r
 348   ------------------------------------------------------------------------------\r
 349   The MSS_I2C_init() function initializes and configures hardware and data\r
 350   structures of one of the SmartFusion MSS I2Cs.\r
 351   ------------------------------------------------------------------------------\r
 352   @param this_i2c:\r
 353     The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 354     identifying the MSS I2C hardware block to be initialized. There are two such\r
 355     data structures, g_mss_i2c0 and g_mss_i2c1, associated with MSS I2C 0 and\r
 356     MSS I2C 1 respectively. This parameter must point to either the g_mss_i2c0\r
 357     or g_mss_i2c1 global data structure defined within the I2C driver.\r
 358 \r
 359   @param ser_address:\r
 360     This parameter sets the I2C serial address being initialized. It is the I2C\r
 361     bus address to which the MSS I2C instance will respond. Any 8 bit address is\r
 362     allowed.\r
 363 \r
 364   @param ser_clock_speed:\r
 365     This parameter sets the I2C serial clock frequency. It selects the divider\r
 366     that will be used to generate the serial clock from the APB clock. It can be\r
 367     one of the following:\r
 368         • MSS_I2C_PCLK_DIV_256\r
 369         • MSS_I2C_PCLK_DIV_224\r
 370         • MSS_I2C_PCLK_DIV_192\r
 371         • MSS_I2C_PCLK_DIV_160\r
 372         • MSS_I2C_PCLK_DIV_960\r
 373         • MSS_I2C_PCLK_DIV_120\r
 374         • MSS_I2C_PCLK_DIV_60\r
 375         • MSS_I2C_BCLK_DIV_8\r
 376  */\r
 377 void MSS_I2C_init\r
 378 (\r
 379         mss_i2c_instance_t * this_i2c,\r
 380         uint8_t ser_address,\r
 381         mss_i2c_clock_divider_t ser_clock_speed\r
 382 );\r
 383 \r
 384 /*******************************************************************************\r
 385  *******************************************************************************\r
 386  *\r
 387  *                           Master specific functions\r
 388  *\r
 389  * The following functions are only used within an I2C master's implementation.\r
 390  */\r
 391 \r
 392 /*-------------------------------------------------------------------------*//**\r
 393   I2C master write function.\r
 394   ------------------------------------------------------------------------------\r
 395   This function initiates an I2C master write transaction. This function returns\r
 396   immediately after initiating the transaction. The content of the write buffer\r
 397   passed as parameter should not be modified until the write transaction\r
 398   completes. It also means that the memory allocated for the write buffer should\r
 399   not be freed or go out of scope before the write completes. You can check for\r
 400   the write transaction completion using the MSS_I2C_status() function.\r
 401   ------------------------------------------------------------------------------\r
 402   @param this_i2c:\r
 403         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 404     identifying the MSS I2C hardware block that will perform the requested\r
 405     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 406     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 407     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 408     within the I2C driver.\r
 409 \r
 410   @param serial_addr:\r
 411         This parameter specifies the serial address of the target I2C device.\r
 412 \r
 413   @param write_buffer:\r
 414         This parameter is a pointer to a buffer holding the data to be written to\r
 415     the target I2C device.\r
 416     Care must be taken not to release the memory used by this buffer before the\r
 417     write transaction completes. For example, it is not appropriate to return\r
 418     from a function allocating this buffer as an array variable before the write\r
 419     transaction completes as this would result in the buffer's memory being\r
 420     de-allocated from the stack when the function returns. This memory could\r
 421     then be subsequently reused and modified causing unexpected data to be\r
 422     written to the target I2C device.\r
 423 \r
 424   @param write_size:\r
 425         Number of bytes held in the write_buffer to be written to the target I2C\r
 426     device.\r
 427 \r
 428  @param options:\r
 429         The options parameter is used to indicate if the I2C bus should be released\r
 430     on completion of the write transaction. Using the MSS_I2C_RELEASE_BUS\r
 431     constant for the options parameter causes a STOP bit to be generated at the\r
 432     end of the write transaction causing the bus to be released for other I2C\r
 433     devices to use. Using the MSS_I2C_HOLD_BUS constant as options parameter\r
 434     prevents a STOP bit from being generated at the end of the write\r
 435     transaction, preventing other I2C devices from initiating a bus transaction.\r
 436  */\r
 437 void MSS_I2C_write\r
 438 (\r
 439         mss_i2c_instance_t * this_i2c,\r
 440         uint8_t serial_addr,\r
 441         const uint8_t * write_buffer,\r
 442         uint16_t write_size,\r
 443     uint8_t options\r
 444 );\r
 445 \r
 446 /*-------------------------------------------------------------------------*//**\r
 447   I2C master read.\r
 448   ------------------------------------------------------------------------------\r
 449   This function initiates an I2C master read transaction. This function returns\r
 450   immediately after initiating the transaction.\r
 451   The content of the read buffer passed as parameter should not be modified\r
 452   until the read transaction completes. It also means that the memory allocated\r
 453   for the read buffer should not be freed or go out of scope before the read\r
 454   completes. You can check for the read transaction completion using the\r
 455   MSS_I2C_status() function.\r
 456   ------------------------------------------------------------------------------\r
 457   @param this_i2c:\r
 458         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 459     identifying the MSS I2C hardware block that will perform the requested\r
 460     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 461     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 462     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 463     within the I2C driver.\r
 464 \r
 465   @param serial_addr:\r
 466         This parameter specifies the serial address of the target I2C device.\r
 467 \r
 468   @param read_buffer\r
 469         Pointer to a buffer where the data received from the target device will be\r
 470     stored.\r
 471     Care must be taken not to release the memory used by this buffer before the\r
 472     read transaction completes. For example, it is not appropriate to return\r
 473     from a function allocating this buffer as an array variable before the read\r
 474     transaction completes as this would result in the buffer's memory being\r
 475     de-allocated from the stack when the function returns. This memory could\r
 476     then be subsequently reallocated resulting in the read transaction\r
 477     corrupting the newly allocated memory.\r
 478 \r
 479   @param read_size:\r
 480         This parameter is the number of bytes to read from the target device. This\r
 481     size must not exceed the size of the read_buffer buffer.\r
 482 \r
 483   @param options:\r
 484         The options parameter is used to indicate if the I2C bus should be released\r
 485     on completion of the read transaction. Using the MSS_I2C_RELEASE_BUS\r
 486     constant for the options parameter causes a STOP bit to be generated at the\r
 487     end of the read transaction causing the bus to be released for other I2C\r
 488     devices to use. Using the MSS_I2C_HOLD_BUS constant as options parameter\r
 489     prevents a STOP bit from being generated at the end of the read transaction,\r
 490     preventing other I2C devices from initiating a bus transaction.\r
 491  */\r
 492 void MSS_I2C_read\r
 493 (\r
 494         mss_i2c_instance_t * this_i2c,\r
 495         uint8_t serial_addr,\r
 496         uint8_t * read_buffer,\r
 497         uint16_t read_size,\r
 498     uint8_t options\r
 499 );\r
 500 \r
 501 /*-------------------------------------------------------------------------*//**\r
 502   I2C master write-read\r
 503   ------------------------------------------------------------------------------\r
 504   This function initiates an I2C write-read transaction where data is first\r
 505   written to the target device before issuing a restart condition and changing\r
 506   the direction of the I2C transaction in order to read from the target device.\r
 507   ------------------------------------------------------------------------------\r
 508   @param this_i2c:\r
 509         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 510     identifying the MSS I2C hardware block that will perform the requested\r
 511     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 512     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 513     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 514     within the I2C driver.\r
 515 \r
 516   @param serial_addr:\r
 517         This parameter specifies the serial address of the target I2C device.\r
 518 \r
 519   @param addr_offset:\r
 520         This parameter is a pointer to the buffer containing the data that will be\r
 521     sent to the slave during the write phase of the write-read transaction. This\r
 522     data is typically used to specify an address offset specifying to the I2C\r
 523     slave device what data it must return during the read phase of the\r
 524     write-read transaction.\r
 525 \r
 526   @param offset_size:\r
 527         This parameter specifies the number of offset bytes to be written during the\r
 528     write phase of the write-read transaction. This is typically the size of the\r
 529     buffer pointed to by the addr_offset parameter.\r
 530 \r
 531   @param read_buffer:\r
 532         This parameter is a pointer to the buffer where the data read from the I2C\r
 533     slave will be stored.\r
 534 \r
 535   @param read_size:\r
 536         This parameter specifies the number of bytes to read from the target I2C\r
 537     slave device. This size must not exceed the size of the buffer pointed to by\r
 538     the read_buffer parameter.\r
 539 \r
 540   @param options:\r
 541         The options parameter is used to indicate if the I2C bus should be released\r
 542     on completion of the write-read transaction. Using the MSS_I2C_RELEASE_BUS\r
 543     constant for the options parameter causes a STOP bit to be generated at the\r
 544     end of the write-read transaction causing the bus to be released for other\r
 545     I2C devices to use. Using the MSS_I2C_HOLD_BUS constant as options parameter\r
 546     prevents a STOP bit from being generated at the end of the write-read\r
 547     transaction, preventing other I2C devices from initiating a bus transaction.\r
 548  */\r
 549 void MSS_I2C_write_read\r
 550 (\r
 551         mss_i2c_instance_t * this_i2c,\r
 552         uint8_t serial_addr,\r
 553         const uint8_t * addr_offset,\r
 554         uint16_t offset_size,\r
 555         uint8_t * read_buffer,\r
 556         uint16_t read_size,\r
 557     uint8_t options\r
 558 );\r
 559 \r
 560 /*-------------------------------------------------------------------------*//**\r
 561   I2C status\r
 562   ------------------------------------------------------------------------------\r
 563   This function indicates the current state of a MSS I2C instance.\r
 564   ------------------------------------------------------------------------------\r
 565   @param this_i2c:\r
 566         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 567     identifying the MSS I2C hardware block that will perform the requested\r
 568     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 569     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 570     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 571     within the I2C driver.\r
 572   ------------------------------------------------------------------------------\r
 573   @return\r
 574     The return value indicates the current state of a MSS I2C instance or the\r
 575     outcome of the previous transaction if no transaction is in progress.\r
 576     Possible return values are:\r
 577       SUCCESS\r
 578         The last I2C transaction has completed successfully.\r
 579       IN_PROGRESS\r
 580         There is an I2C transaction in progress.\r
 581       FAILED\r
 582         The last I2C transaction failed.\r
 583 \r
 584  */\r
 585 mss_i2c_status_t MSS_I2C_get_status\r
 586 (\r
 587     mss_i2c_instance_t * this_i2c\r
 588 );\r
 589 \r
 590 /*-------------------------------------------------------------------------*//**\r
 591   Wait for I2C transaction completion.\r
 592   ------------------------------------------------------------------------------\r
 593   This function waits for the current I2C transaction to complete. The return\r
 594   value indicates whether the last I2C transaction was successful, or is still\r
 595   in progress, or failed.\r
 596   ------------------------------------------------------------------------------\r
 597   @param this_i2c:\r
 598     The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 599     identifying the MSS I2C hardware block that will perform the requested\r
 600     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 601     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 602     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 603     within the I2C driver.\r
 604   ------------------------------------------------------------------------------\r
 605   @return\r
 606     The return value indicates the outcome of the last I2C transaction. It can\r
 607     be one of the following:\r
 608       MSS_I2C_SUCCESS\r
 609         The last I2C transaction has completed successfully.\r
 610       MSS_I2C_IN_PROGRESS\r
 611         The current I2C transaction is still in progress.\r
 612       MSS_I2C_FAILED\r
 613         The last I2C transaction failed.\r
 614  */\r
 615 mss_i2c_status_t MSS_I2C_wait_complete\r
 616 (\r
 617     mss_i2c_instance_t * this_i2c\r
 618 );\r
 619 \r
 620 \r
 621 /*******************************************************************************\r
 622  *******************************************************************************\r
 623  *\r
 624  *                           Slave specific functions\r
 625  *\r
 626  * The following functions are only used within the implementation of an I2C\r
 627  * slave device.\r
 628  */\r
 629 \r
 630 /*-------------------------------------------------------------------------*//**\r
 631   I2C slave transmit buffer configuration.\r
 632   ------------------------------------------------------------------------------\r
 633   This function specifies the memory buffer holding the data that will be sent\r
 634   to the I2C master when this MSS I2C instance is the target of an I2C read or\r
 635   write-read transaction.\r
 636   ------------------------------------------------------------------------------\r
 637   @param this_i2c:\r
 638         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 639     identifying the MSS I2C hardware block that will perform the requested\r
 640     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 641     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 642     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 643     within the I2C driver.\r
 644 \r
 645   @param tx_buffer:\r
 646         This parameter is a pointer to the memory buffer holding the data to be\r
 647     returned to the I2C master when this MSS I2C instance is the target of an\r
 648     I2C read or write-read transaction.\r
 649 \r
 650   @param tx_size:\r
 651         Size of the transmit buffer pointed to by the tx_buffer parameter.\r
 652  */\r
 653 void MSS_I2C_set_slave_tx_buffer\r
 654 (\r
 655         mss_i2c_instance_t * this_i2c,\r
 656         uint8_t * tx_buffer,\r
 657         uint16_t tx_size\r
 658 );\r
 659 \r
 660 /*-------------------------------------------------------------------------*//**\r
 661   I2C slave receive buffer configuration.\r
 662   ------------------------------------------------------------------------------\r
 663   This function specifies the memory buffer that will be used by the MSS I2C\r
 664   instance to receive data when it is a slave. This buffer is the memory where\r
 665   data will be stored when the MSS I2C is the target of an I2C master write\r
 666   transaction (i.e. when it is the slave).\r
 667   ------------------------------------------------------------------------------\r
 668   @param this_i2c:\r
 669         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 670     identifying the MSS I2C hardware block that will perform the requested\r
 671     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 672     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 673     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 674     within the I2C driver.\r
 675 \r
 676   @param rx_buffer:\r
 677         This parameter is a pointer to the memory buffer allocated by the caller\r
 678     software to be used as a slave receive buffer.\r
 679 \r
 680   @param rx_size:\r
 681         Size of the slave receive buffer. This is the amount of memory that is\r
 682     allocated to the buffer pointed to by rx_buffer.\r
 683     Note:   This buffer size will indirectly specify the maximum I2C write\r
 684             transaction length this MSS I2C instance can be the target of. This\r
 685             is because this MSS I2C instance will respond to further received\r
 686             bytes with a non-acknowledge bit (NACK) as soon as its receive\r
 687             buffer is full. This will cause the write transaction to fail.\r
 688  */\r
 689 void MSS_I2C_set_slave_rx_buffer\r
 690 (\r
 691         mss_i2c_instance_t * this_i2c,\r
 692         uint8_t * rx_buffer,\r
 693         uint16_t rx_size\r
 694 );\r
 695 \r
 696 /*-------------------------------------------------------------------------*//**\r
 697   I2C slave memory offset length configuration.\r
 698   ------------------------------------------------------------------------------\r
 699   This function is used as part of the configuration of a MSS I2C instance for\r
 700   operation as a slave supporting write-read transactions. It specifies the\r
 701   number of bytes expected as part of the write phase of a write-read\r
 702   transaction. The bytes received during the write phase of a write-read\r
 703   transaction will be interpreted as an offset into the slave’s transmit buffer.\r
 704   This allows random access into the I2C slave transmit buffer from a remote\r
 705   I2C master.\r
 706   ------------------------------------------------------------------------------\r
 707   @param this_i2c:\r
 708         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 709     identifying the MSS I2C hardware block that will perform the requested\r
 710     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 711     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 712     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 713     within the I2C driver.\r
 714 \r
 715   @param offset_length:\r
 716         The offset_length parameter configures the number of bytes to be interpreted\r
 717     by the MSS I2C slave as a memory offset value during the write phase of\r
 718     write-read transactions.\r
 719  */\r
 720 void MSS_I2C_set_slave_mem_offset_length\r
 721 (\r
 722         mss_i2c_instance_t * this_i2c,\r
 723         uint8_t offset_length\r
 724 );\r
 725 \r
 726 /*-------------------------------------------------------------------------*//**\r
 727   I2C write handler registration.\r
 728   ------------------------------------------------------------------------------\r
 729   Register the function that will be called to process the data written to this\r
 730   MSS I2C instance when it is the slave in an I2C write transaction.\r
 731   Note: The write handler is not called as a result of a write-read transaction.\r
 732         The write data of a write read transaction is interpreted as an offset\r
 733         into the slave’s transmit buffer and handled by the driver.\r
 734   ------------------------------------------------------------------------------\r
 735   @param this_i2c:\r
 736         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 737     identifying the MSS I2C hardware block that will perform the requested\r
 738     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 739     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 740     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 741     within the I2C driver.\r
 742 \r
 743   @param handler:\r
 744         Pointer to the function that will process the I2C write request.\r
 745  */\r
 746 void MSS_I2C_register_write_handler\r
 747 (\r
 748         mss_i2c_instance_t * this_i2c,\r
 749         mss_i2c_slave_wr_handler_t handler\r
 750 );\r
 751 \r
 752 /*-------------------------------------------------------------------------*//**\r
 753   I2C slave receive enable.\r
 754   ------------------------------------------------------------------------------\r
 755   Enables the MSS I2C instance identified through the this_i2c parameter to\r
 756   receive data when it is the target of an I2C write or write-read transaction.\r
 757   ------------------------------------------------------------------------------\r
 758   @param this_i2c:\r
 759         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 760     identifying the MSS I2C hardware block that will perform the requested\r
 761     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 762     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 763     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 764     within the I2C driver.\r
 765  */\r
 766 void MSS_I2C_enable_slave_rx\r
 767 (\r
 768         mss_i2c_instance_t * this_i2c\r
 769 );\r
 770 \r
 771 #ifdef __cplusplus\r
 772 }\r
 773 #endif\r
 774 \r
 775 #endif /*MSS_I2C_H_*/\r