git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A2F200_IAR_and_Keil/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 /* FreeRTOS includes. */\r
 198 #include "FreeRTOS.h"\r
 199 #include "task.h"\r
 200 #include "semphr.h"\r
 201 \r
 202 #ifdef __cplusplus\r
 203 extern "C" {\r
 204 #endif\r
 205 \r
 206 /*-------------------------------------------------------------------------*//**\r
 207   The mss_i2c_clock_divider_t type is used to specify the divider to be applied\r
 208   to the MSS I2C BCLK signal in order to generate the I2C clock.\r
 209  */\r
 210 typedef enum mss_i2c_clock_divider {\r
 211     MSS_I2C_PCLK_DIV_256 = 0,\r
 212     MSS_I2C_PCLK_DIV_224,\r
 213     MSS_I2C_PCLK_DIV_192,\r
 214     MSS_I2C_PCLK_DIV_160,\r
 215     MSS_I2C_PCLK_DIV_960,\r
 216     MSS_I2C_PCLK_DIV_120,\r
 217     MSS_I2C_PCLK_DIV_60,\r
 218     MSS_I2C_BCLK_DIV_8\r
 219 } mss_i2c_clock_divider_t;\r
 220 \r
 221 /*-------------------------------------------------------------------------*//**\r
 222   The MSS_I2C_RELEASE_BUS constant is used to specify the options parameter to\r
 223   functions MSS_I2C_read(), MSS_I2C_write() and MSS_I2C_write_read() to indicate\r
 224   that a STOP bit must be generated at the end of the I2C transaction to release\r
 225   the bus.\r
 226  */\r
 227 #define MSS_I2C_RELEASE_BUS     0x00\r
 228 \r
 229 /*-------------------------------------------------------------------------*//**\r
 230   The MSS_I2C_HOLD_BUS constant is used to specify the options parameter to\r
 231   functions MSS_I2C_read(), MSS_I2C_write() and MSS_I2C_write_read() to indicate\r
 232   that a STOP bit must not be generated at the end of the I2C transaction in\r
 233   order to retain the bus ownership. This will cause the next transaction to\r
 234   begin with a repeated START bit and no STOP bit between the transactions.\r
 235  */\r
 236 #define MSS_I2C_HOLD_BUS        0x01\r
 237 \r
 238 /*-------------------------------------------------------------------------*//**\r
 239   The mss_i2c_status_t type is used to report the status of I2C transactions.\r
 240  */\r
 241 typedef enum mss_i2c_status\r
 242 {\r
 243     MSS_I2C_SUCCESS = 0,\r
 244     MSS_I2C_IN_PROGRESS,\r
 245     MSS_I2C_FAILED\r
 246 } mss_i2c_status_t;\r
 247 \r
 248 /*-------------------------------------------------------------------------*//**\r
 249   The mss_i2c_slave_handler_ret_t type is used by slave write handler functions\r
 250   to indicate whether the received data buffer should be released or not.\r
 251  */\r
 252 typedef enum mss_i2c_slave_handler_ret {\r
 253     MSS_I2C_REENABLE_SLAVE_RX = 0,\r
 254     MSS_I2C_PAUSE_SLAVE_RX = 1\r
 255 } mss_i2c_slave_handler_ret_t;\r
 256 \r
 257 /*-------------------------------------------------------------------------*//**\r
 258   Slave write handler functions prototype.\r
 259   ------------------------------------------------------------------------------\r
 260   This defines the function prototype that must be followed by MSS I2C slave\r
 261   write handler functions. These functions are registered with the MSS I2C driver\r
 262   through the MSS_I2C_register_write_handler() function.\r
 263 \r
 264   Declaring and Implementing Slave Write Handler Functions:\r
 265     Slave write handler functions should follow the following prototype:\r
 266     mss_i2c_slave_handler_ret_t write_handler( uint8_t * data, uint16_t size );\r
 267 \r
 268     The data parameter is a pointer to a buffer (received data buffer) holding\r
 269     the data written to the MSS I2C slave.\r
 270     The size parameter is the number of bytes held in the received data buffer.\r
 271     Handler functions must return one of the following values:\r
 272         • MSS_I2C_REENABLE_SLAVE_RX\r
 273         • MSS_I2C_PAUSE_SLAVE_RX.\r
 274     If the handler function returns MSS_I2C_REENABLE_SLAVE_RX, the driver will\r
 275     release the received data buffer and allow further I2C write transactions to\r
 276     the MSS I2C slave to take place.\r
 277     If the handler function returns MSS_I2C_PAUSE_SLAVE_RX, the MSS I2C slave\r
 278     will respond to subsequent write requests with a non-acknowledge bit (NACK),\r
 279     until the received data buffer content has been processed by some other part\r
 280     of the software application.\r
 281     A call to MSS_I2C_enable_slave_rx() is required at some point after\r
 282     returning MSS_I2C_PAUSE_SLAVE_RX in order to release the received data\r
 283     buffer so it can be used to store data received by subsequent I2C write\r
 284     transactions.\r
 285  */\r
 286 typedef mss_i2c_slave_handler_ret_t (*mss_i2c_slave_wr_handler_t)( uint8_t *, uint16_t );\r
 287 \r
 288 /*-------------------------------------------------------------------------*//**\r
 289   mss_i2c_instance_t\r
 290   ------------------------------------------------------------------------------\r
 291   There is one instance of this structure for each of the microcontroller\r
 292   subsystem's I2Cs. Instances of this structure are used to identify a specific\r
 293   I2C. A pointer to an instance of the mss_i2c_instance_t structure is passed as\r
 294   the first parameter to MSS I2C driver functions to identify which I2C should\r
 295   perform the requested operation.\r
 296  */\r
 297 typedef struct mss_i2c_instance\r
 298 {\r
 299         uint_fast8_t ser_address;\r
 300         /* Transmit related info:*/\r
 301         uint_fast8_t target_addr;\r
 302 \r
 303         /* Current transaction type (WRITE, READ, RANDOM_READ)*/\r
 304         uint8_t transaction;\r
 305 \r
 306         uint_fast16_t random_read_addr;\r
 307 \r
 308     uint8_t options;\r
 309 \r
 310         /* I2C hardware instance identification */\r
 311     IRQn_Type  irqn;\r
 312     I2C_TypeDef * hw_reg;\r
 313     I2C_BitBand_TypeDef * hw_reg_bit;\r
 314 \r
 315         /* TX INFO: */\r
 316         const uint8_t * tx_buffer;\r
 317         uint_fast16_t tx_size;\r
 318         uint_fast16_t tx_idx;\r
 319         uint_fast8_t dir;\r
 320 \r
 321         /* RX INFO: */\r
 322         uint8_t * rx_buffer;\r
 323         uint_fast16_t rx_size;\r
 324         uint_fast16_t rx_idx;\r
 325 \r
 326         /* status variable: */\r
 327     volatile mss_i2c_status_t status;\r
 328 \r
 329         /* Slave data: */\r
 330         uint_fast8_t slave_mem_offset_length;\r
 331         mss_i2c_slave_wr_handler_t slave_write_handler;\r
 332         \r
 333         /* Used to get access to and wait for completion of an I2C transaction. */\r
 334         SemaphoreHandle_t xI2CCompleteSemaphore;\r
 335         \r
 336 } mss_i2c_instance_t;\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 0. A pointer to g_mss_i2c0 is passed as the first\r
 341   parameter to MSS I2C driver functions to indicate that MSS I2C 0 should\r
 342   perform the requested operation.\r
 343  */\r
 344 extern mss_i2c_instance_t g_mss_i2c0;\r
 345 \r
 346 /*-------------------------------------------------------------------------*//**\r
 347   This instance of mss_i2c_instance_t holds all data related to the operations\r
 348   performed by MSS I2C 1. A pointer to g_mss_i2c1 is passed as the first\r
 349   parameter to MSS I2C driver functions to indicate that MSS I2C 1 should\r
 350   perform the requested operation.\r
 351  */\r
 352 extern mss_i2c_instance_t g_mss_i2c1;\r
 353 \r
 354 /*-------------------------------------------------------------------------*//**\r
 355   MSS I2C initialisation routine.\r
 356   ------------------------------------------------------------------------------\r
 357   The MSS_I2C_init() function initializes and configures hardware and data\r
 358   structures of one of the SmartFusion MSS I2Cs.\r
 359   ------------------------------------------------------------------------------\r
 360   @param this_i2c:\r
 361     The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 362     identifying the MSS I2C hardware block to be initialized. There are two such\r
 363     data structures, g_mss_i2c0 and g_mss_i2c1, associated with MSS I2C 0 and\r
 364     MSS I2C 1 respectively. This parameter must point to either the g_mss_i2c0\r
 365     or g_mss_i2c1 global data structure defined within the I2C driver.\r
 366 \r
 367   @param ser_address:\r
 368     This parameter sets the I2C serial address being initialized. It is the I2C\r
 369     bus address to which the MSS I2C instance will respond. Any 8 bit address is\r
 370     allowed.\r
 371 \r
 372   @param ser_clock_speed:\r
 373     This parameter sets the I2C serial clock frequency. It selects the divider\r
 374     that will be used to generate the serial clock from the APB clock. It can be\r
 375     one of the following:\r
 376         • MSS_I2C_PCLK_DIV_256\r
 377         • MSS_I2C_PCLK_DIV_224\r
 378         • MSS_I2C_PCLK_DIV_192\r
 379         • MSS_I2C_PCLK_DIV_160\r
 380         • MSS_I2C_PCLK_DIV_960\r
 381         • MSS_I2C_PCLK_DIV_120\r
 382         • MSS_I2C_PCLK_DIV_60\r
 383         • MSS_I2C_BCLK_DIV_8\r
 384  */\r
 385 void MSS_I2C_init\r
 386 (\r
 387         mss_i2c_instance_t * this_i2c,\r
 388         uint8_t ser_address,\r
 389         mss_i2c_clock_divider_t ser_clock_speed\r
 390 );\r
 391 \r
 392 /*******************************************************************************\r
 393  *******************************************************************************\r
 394  *\r
 395  *                           Master specific functions\r
 396  *\r
 397  * The following functions are only used within an I2C master's implementation.\r
 398  */\r
 399 \r
 400 /*-------------------------------------------------------------------------*//**\r
 401   I2C master write function.\r
 402   ------------------------------------------------------------------------------\r
 403   This function initiates an I2C master write transaction. This function returns\r
 404   immediately after initiating the transaction. The content of the write buffer\r
 405   passed as parameter should not be modified until the write transaction\r
 406   completes. It also means that the memory allocated for the write buffer should\r
 407   not be freed or go out of scope before the write completes. You can check for\r
 408   the write transaction completion using the MSS_I2C_status() function.\r
 409   ------------------------------------------------------------------------------\r
 410   @param this_i2c:\r
 411         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 412     identifying the MSS I2C hardware block that will perform the requested\r
 413     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 414     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 415     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 416     within the I2C driver.\r
 417 \r
 418   @param serial_addr:\r
 419         This parameter specifies the serial address of the target I2C device.\r
 420 \r
 421   @param write_buffer:\r
 422         This parameter is a pointer to a buffer holding the data to be written to\r
 423     the target I2C device.\r
 424     Care must be taken not to release the memory used by this buffer before the\r
 425     write transaction completes. For example, it is not appropriate to return\r
 426     from a function allocating this buffer as an array variable before the write\r
 427     transaction completes as this would result in the buffer's memory being\r
 428     de-allocated from the stack when the function returns. This memory could\r
 429     then be subsequently reused and modified causing unexpected data to be\r
 430     written to the target I2C device.\r
 431 \r
 432   @param write_size:\r
 433         Number of bytes held in the write_buffer to be written to the target I2C\r
 434     device.\r
 435 \r
 436  @param options:\r
 437         The options parameter is used to indicate if the I2C bus should be released\r
 438     on completion of the write transaction. Using the MSS_I2C_RELEASE_BUS\r
 439     constant for the options parameter causes a STOP bit to be generated at the\r
 440     end of the write transaction causing the bus to be released for other I2C\r
 441     devices to use. Using the MSS_I2C_HOLD_BUS constant as options parameter\r
 442     prevents a STOP bit from being generated at the end of the write\r
 443     transaction, preventing other I2C devices from initiating a bus transaction.\r
 444  */\r
 445 void MSS_I2C_write\r
 446 (\r
 447         mss_i2c_instance_t * this_i2c,\r
 448         uint8_t serial_addr,\r
 449         const uint8_t * write_buffer,\r
 450         uint16_t write_size,\r
 451     uint8_t options\r
 452 );\r
 453 \r
 454 /*-------------------------------------------------------------------------*//**\r
 455   I2C master read.\r
 456   ------------------------------------------------------------------------------\r
 457   This function initiates an I2C master read transaction. This function returns\r
 458   immediately after initiating the transaction.\r
 459   The content of the read buffer passed as parameter should not be modified\r
 460   until the read transaction completes. It also means that the memory allocated\r
 461   for the read buffer should not be freed or go out of scope before the read\r
 462   completes. You can check for the read transaction completion using the\r
 463   MSS_I2C_status() function.\r
 464   ------------------------------------------------------------------------------\r
 465   @param this_i2c:\r
 466         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 467     identifying the MSS I2C hardware block that will perform the requested\r
 468     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 469     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 470     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 471     within the I2C driver.\r
 472 \r
 473   @param serial_addr:\r
 474         This parameter specifies the serial address of the target I2C device.\r
 475 \r
 476   @param read_buffer\r
 477         Pointer to a buffer where the data received from the target device will be\r
 478     stored.\r
 479     Care must be taken not to release the memory used by this buffer before the\r
 480     read transaction completes. For example, it is not appropriate to return\r
 481     from a function allocating this buffer as an array variable before the read\r
 482     transaction completes as this would result in the buffer's memory being\r
 483     de-allocated from the stack when the function returns. This memory could\r
 484     then be subsequently reallocated resulting in the read transaction\r
 485     corrupting the newly allocated memory.\r
 486 \r
 487   @param read_size:\r
 488         This parameter is the number of bytes to read from the target device. This\r
 489     size must not exceed the size of the read_buffer buffer.\r
 490 \r
 491   @param options:\r
 492         The options parameter is used to indicate if the I2C bus should be released\r
 493     on completion of the read transaction. Using the MSS_I2C_RELEASE_BUS\r
 494     constant for the options parameter causes a STOP bit to be generated at the\r
 495     end of the read transaction causing the bus to be released for other I2C\r
 496     devices to use. Using the MSS_I2C_HOLD_BUS constant as options parameter\r
 497     prevents a STOP bit from being generated at the end of the read transaction,\r
 498     preventing other I2C devices from initiating a bus transaction.\r
 499  */\r
 500 void MSS_I2C_read\r
 501 (\r
 502         mss_i2c_instance_t * this_i2c,\r
 503         uint8_t serial_addr,\r
 504         uint8_t * read_buffer,\r
 505         uint16_t read_size,\r
 506     uint8_t options\r
 507 );\r
 508 \r
 509 /*-------------------------------------------------------------------------*//**\r
 510   I2C master write-read\r
 511   ------------------------------------------------------------------------------\r
 512   This function initiates an I2C write-read transaction where data is first\r
 513   written to the target device before issuing a restart condition and changing\r
 514   the direction of the I2C transaction in order to read from the target device.\r
 515   ------------------------------------------------------------------------------\r
 516   @param this_i2c:\r
 517         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 518     identifying the MSS I2C hardware block that will perform the requested\r
 519     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 520     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 521     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 522     within the I2C driver.\r
 523 \r
 524   @param serial_addr:\r
 525         This parameter specifies the serial address of the target I2C device.\r
 526 \r
 527   @param addr_offset:\r
 528         This parameter is a pointer to the buffer containing the data that will be\r
 529     sent to the slave during the write phase of the write-read transaction. This\r
 530     data is typically used to specify an address offset specifying to the I2C\r
 531     slave device what data it must return during the read phase of the\r
 532     write-read transaction.\r
 533 \r
 534   @param offset_size:\r
 535         This parameter specifies the number of offset bytes to be written during the\r
 536     write phase of the write-read transaction. This is typically the size of the\r
 537     buffer pointed to by the addr_offset parameter.\r
 538 \r
 539   @param read_buffer:\r
 540         This parameter is a pointer to the buffer where the data read from the I2C\r
 541     slave will be stored.\r
 542 \r
 543   @param read_size:\r
 544         This parameter specifies the number of bytes to read from the target I2C\r
 545     slave device. This size must not exceed the size of the buffer pointed to by\r
 546     the read_buffer parameter.\r
 547 \r
 548   @param options:\r
 549         The options parameter is used to indicate if the I2C bus should be released\r
 550     on completion of the write-read transaction. Using the MSS_I2C_RELEASE_BUS\r
 551     constant for the options parameter causes a STOP bit to be generated at the\r
 552     end of the write-read transaction causing the bus to be released for other\r
 553     I2C devices to use. Using the MSS_I2C_HOLD_BUS constant as options parameter\r
 554     prevents a STOP bit from being generated at the end of the write-read\r
 555     transaction, preventing other I2C devices from initiating a bus transaction.\r
 556  */\r
 557 void MSS_I2C_write_read\r
 558 (\r
 559         mss_i2c_instance_t * this_i2c,\r
 560         uint8_t serial_addr,\r
 561         const uint8_t * addr_offset,\r
 562         uint16_t offset_size,\r
 563         uint8_t * read_buffer,\r
 564         uint16_t read_size,\r
 565     uint8_t options\r
 566 );\r
 567 \r
 568 /*-------------------------------------------------------------------------*//**\r
 569   I2C status\r
 570   ------------------------------------------------------------------------------\r
 571   This function indicates the current state of a MSS I2C instance.\r
 572   ------------------------------------------------------------------------------\r
 573   @param this_i2c:\r
 574         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 575     identifying the MSS I2C hardware block that will perform the requested\r
 576     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 577     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 578     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 579     within the I2C driver.\r
 580   ------------------------------------------------------------------------------\r
 581   @return\r
 582     The return value indicates the current state of a MSS I2C instance or the\r
 583     outcome of the previous transaction if no transaction is in progress.\r
 584     Possible return values are:\r
 585       SUCCESS\r
 586         The last I2C transaction has completed successfully.\r
 587       IN_PROGRESS\r
 588         There is an I2C transaction in progress.\r
 589       FAILED\r
 590         The last I2C transaction failed.\r
 591 \r
 592  */\r
 593 mss_i2c_status_t MSS_I2C_get_status\r
 594 (\r
 595     mss_i2c_instance_t * this_i2c\r
 596 );\r
 597 \r
 598 /*-------------------------------------------------------------------------*//**\r
 599   Wait for I2C transaction completion.\r
 600   ------------------------------------------------------------------------------\r
 601   This function waits for the current I2C transaction to complete. The return\r
 602   value indicates whether the last I2C transaction was successful, or is still\r
 603   in progress, or failed.\r
 604   ------------------------------------------------------------------------------\r
 605   @param this_i2c:\r
 606     The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 607     identifying the MSS I2C hardware block that will perform the requested\r
 608     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 609     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 610     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 611     within the I2C driver.\r
 612   ------------------------------------------------------------------------------\r
 613   @return\r
 614     The return value indicates the outcome of the last I2C transaction. It can\r
 615     be one of the following:\r
 616       MSS_I2C_SUCCESS\r
 617         The last I2C transaction has completed successfully.\r
 618       MSS_I2C_IN_PROGRESS\r
 619         The current I2C transaction is still in progress.\r
 620       MSS_I2C_FAILED\r
 621         The last I2C transaction failed.\r
 622  */\r
 623 mss_i2c_status_t MSS_I2C_wait_complete\r
 624 (\r
 625     mss_i2c_instance_t * this_i2c\r
 626 );\r
 627 \r
 628 \r
 629 /*******************************************************************************\r
 630  *******************************************************************************\r
 631  *\r
 632  *                           Slave specific functions\r
 633  *\r
 634  * The following functions are only used within the implementation of an I2C\r
 635  * slave device.\r
 636  */\r
 637 \r
 638 /*-------------------------------------------------------------------------*//**\r
 639   I2C slave transmit buffer configuration.\r
 640   ------------------------------------------------------------------------------\r
 641   This function specifies the memory buffer holding the data that will be sent\r
 642   to the I2C master when this MSS I2C instance is the target of an I2C read or\r
 643   write-read transaction.\r
 644   ------------------------------------------------------------------------------\r
 645   @param this_i2c:\r
 646         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 647     identifying the MSS I2C hardware block that will perform the requested\r
 648     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 649     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 650     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 651     within the I2C driver.\r
 652 \r
 653   @param tx_buffer:\r
 654         This parameter is a pointer to the memory buffer holding the data to be\r
 655     returned to the I2C master when this MSS I2C instance is the target of an\r
 656     I2C read or write-read transaction.\r
 657 \r
 658   @param tx_size:\r
 659         Size of the transmit buffer pointed to by the tx_buffer parameter.\r
 660  */\r
 661 void MSS_I2C_set_slave_tx_buffer\r
 662 (\r
 663         mss_i2c_instance_t * this_i2c,\r
 664         uint8_t * tx_buffer,\r
 665         uint16_t tx_size\r
 666 );\r
 667 \r
 668 /*-------------------------------------------------------------------------*//**\r
 669   I2C slave receive buffer configuration.\r
 670   ------------------------------------------------------------------------------\r
 671   This function specifies the memory buffer that will be used by the MSS I2C\r
 672   instance to receive data when it is a slave. This buffer is the memory where\r
 673   data will be stored when the MSS I2C is the target of an I2C master write\r
 674   transaction (i.e. when it is the slave).\r
 675   ------------------------------------------------------------------------------\r
 676   @param this_i2c:\r
 677         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 678     identifying the MSS I2C hardware block that will perform the requested\r
 679     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 680     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 681     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 682     within the I2C driver.\r
 683 \r
 684   @param rx_buffer:\r
 685         This parameter is a pointer to the memory buffer allocated by the caller\r
 686     software to be used as a slave receive buffer.\r
 687 \r
 688   @param rx_size:\r
 689         Size of the slave receive buffer. This is the amount of memory that is\r
 690     allocated to the buffer pointed to by rx_buffer.\r
 691     Note:   This buffer size will indirectly specify the maximum I2C write\r
 692             transaction length this MSS I2C instance can be the target of. This\r
 693             is because this MSS I2C instance will respond to further received\r
 694             bytes with a non-acknowledge bit (NACK) as soon as its receive\r
 695             buffer is full. This will cause the write transaction to fail.\r
 696  */\r
 697 void MSS_I2C_set_slave_rx_buffer\r
 698 (\r
 699         mss_i2c_instance_t * this_i2c,\r
 700         uint8_t * rx_buffer,\r
 701         uint16_t rx_size\r
 702 );\r
 703 \r
 704 /*-------------------------------------------------------------------------*//**\r
 705   I2C slave memory offset length configuration.\r
 706   ------------------------------------------------------------------------------\r
 707   This function is used as part of the configuration of a MSS I2C instance for\r
 708   operation as a slave supporting write-read transactions. It specifies the\r
 709   number of bytes expected as part of the write phase of a write-read\r
 710   transaction. The bytes received during the write phase of a write-read\r
 711   transaction will be interpreted as an offset into the slave’s transmit buffer.\r
 712   This allows random access into the I2C slave transmit buffer from a remote\r
 713   I2C master.\r
 714   ------------------------------------------------------------------------------\r
 715   @param this_i2c:\r
 716         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 717     identifying the MSS I2C hardware block that will perform the requested\r
 718     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 719     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 720     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 721     within the I2C driver.\r
 722 \r
 723   @param offset_length:\r
 724         The offset_length parameter configures the number of bytes to be interpreted\r
 725     by the MSS I2C slave as a memory offset value during the write phase of\r
 726     write-read transactions.\r
 727  */\r
 728 void MSS_I2C_set_slave_mem_offset_length\r
 729 (\r
 730         mss_i2c_instance_t * this_i2c,\r
 731         uint8_t offset_length\r
 732 );\r
 733 \r
 734 /*-------------------------------------------------------------------------*//**\r
 735   I2C write handler registration.\r
 736   ------------------------------------------------------------------------------\r
 737   Register the function that will be called to process the data written to this\r
 738   MSS I2C instance when it is the slave in an I2C write transaction.\r
 739   Note: The write handler is not called as a result of a write-read transaction.\r
 740         The write data of a write read transaction is interpreted as an offset\r
 741         into the slave’s transmit buffer and handled by the driver.\r
 742   ------------------------------------------------------------------------------\r
 743   @param this_i2c:\r
 744         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 745     identifying the MSS I2C hardware block that will perform the requested\r
 746     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 747     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 748     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 749     within the I2C driver.\r
 750 \r
 751   @param handler:\r
 752         Pointer to the function that will process the I2C write request.\r
 753  */\r
 754 void MSS_I2C_register_write_handler\r
 755 (\r
 756         mss_i2c_instance_t * this_i2c,\r
 757         mss_i2c_slave_wr_handler_t handler\r
 758 );\r
 759 \r
 760 /*-------------------------------------------------------------------------*//**\r
 761   I2C slave receive enable.\r
 762   ------------------------------------------------------------------------------\r
 763   Enables the MSS I2C instance identified through the this_i2c parameter to\r
 764   receive data when it is the target of an I2C write or write-read transaction.\r
 765   ------------------------------------------------------------------------------\r
 766   @param this_i2c:\r
 767         The this_i2c parameter is a pointer to an mss_i2c_instance_t structure\r
 768     identifying the MSS I2C hardware block that will perform the requested\r
 769     function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,\r
 770     associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must\r
 771     point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined\r
 772     within the I2C driver.\r
 773  */\r
 774 void MSS_I2C_enable_slave_rx\r
 775 (\r
 776         mss_i2c_instance_t * this_i2c\r
 777 );\r
 778 \r
 779 #ifdef __cplusplus\r
 780 }\r
 781 #endif\r
 782 \r
 783 #endif /*MSS_I2C_H_*/\r