git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/RISC-V_Renode_Emulator_SoftConsole/Microsemi_Code/drivers/CoreI2C/core_i2c.h

   1 /*******************************************************************************\r
   2  * (c) Copyright 2009-2015 Microsemi SoC Products Group.  All rights reserved.\r
   3  * \r
   4  * CoreI2C software driver Application Programming Interface.\r
   5  * This file contains defines and function declarations allowing to interface\r
   6  * with the CoreI2C software driver.\r
   7  * \r
   8  * SVN $Revision: 7984 $\r
   9  * SVN $Date: 2015-10-12 12:07:40 +0530 (Mon, 12 Oct 2015) $\r
  10  */\r
  11 /*=========================================================================*//**\r
  12   @mainpage CoreI2C Bare Metal Driver.\r
  13    The CoreI2C bare metal software driver supports I2C master and slave\r
  14    operations.\r
  15 \r
  16   @section intro_sec Introduction\r
  17   The CoreI2C driver provides a set of functions for controlling the Microsemi\r
  18   CoreI2C hardware IP. The driver supports up to 16 separate I2C channels per\r
  19   CoreI2C instance, with common slave address settings shared between channels\r
  20   on a device.\r
  21   \r
  22   Optional features of the CoreI2C allow it operate with I2C based protocols\r
  23   such as System Management Bus (SMBus), Power Management Bus (PMBus) and\r
  24   Intelligent Platform Management Interface (IPMI). This driver provides support\r
  25   for these features when enabled in the CoreI2C IP.\r
  26   \r
  27   The major features provided by CoreI2C driver are:\r
  28     - Support for configuring the I2C channels of each CoreI2C peripheral.\r
  29     - I2C master operations.\r
  30     - I2C slave operations.\r
  31     - SMBus related operations.\r
  32 \r
  33   This driver can be used as part of a bare metal system where no operating \r
  34   system  is available. The driver can be adapted for use as part of an \r
  35   operating system, but the implementation of the adaptation layer between the \r
  36   driver and  the operating system's driver model is outside the scope of this \r
  37   driver.\r
  38   \r
  39   @section hw_dependencies Hardware Flow Dependencies\r
  40   Your application software should configure the CoreI2C driver through\r
  41   calls to the I2C_init() function for each CoreI2C instance in the\r
  42   hardware design.  The configuration parameters include the CoreI2C hardware\r
  43   instance base address and other runtime parameters, such as the I2C serial\r
  44   clock frequency and I2C device address.\r
  45   \r
  46   Once channel 0 of a CoreI2C peripheral has been initialized via I2C_init(),\r
  47   any additional channels present should be configured by calling\r
  48   I2C_channel_init() for each of the remaining channels.\r
  49   \r
  50   No CoreI2C hardware configuration parameters are used by the driver, apart\r
  51   from the CoreI2C hardware instance base address. Hence, no additional\r
  52   configuration files are required to use the driver. \r
  53   \r
  54   Interrupt Control\r
  55   The CoreI2C driver has to enable and disable the generation of interrupts by\r
  56   CoreI2C at various times when it is operating. This enabling and disabling of\r
  57   interrupts must be done through the system\92s interrupt controller. For that\r
  58   reason, the method of controlling the CoreI2C interrupt is system specific\r
  59   and it is necessary to customize the I2C_enable_irq() and I2C_disable_irq()\r
  60   functions. These functions are found in the file i2c_interrupt.c. Their\r
  61   default implementation fires an assertion to attract attention to the fact\r
  62   that these functions must be modified.\r
  63   \r
  64   The implementation of the I2C_enable_irq() function should permit interrupts\r
  65   generated by a CoreI2C instance to interrupt the processor. The implementation\r
  66   of the I2C_disable_irq() function should prevent interrupts generated by a\r
  67   CoreI2C instance from interrupting the processor. Please refer to the provided\r
  68   example projects for a working implementation of these functions.\r
  69   \r
  70   The function I2C_register_write_handler() is used to register a write handler\r
  71   function with the CoreI2C driver that it calls on completion of an I2C write\r
  72   transaction by the CoreI2C slave. It is your responsibility to create and\r
  73   register the implementation of this handler function that processes or\r
  74   trigger the processing of the received data.\r
  75   \r
  76   The SMBSUS and SMBALERT interrupts are related to the SMBus interface and are\r
  77   enabled and disabled through I2C_enable_smbus_irq() and \r
  78   I2C_disable_smbus_irq() respectively. It is your responsibility to create\r
  79   interrupt handler functions in your application to get the desired response\r
  80   for the SMBus interrupts.\r
  81 \r
  82   Note: You must include the path to any application header files that are\r
  83         included in the i2c_interrupt.c file, as an include path in your\r
  84         project\92s compiler settings. The details of how to do this will depend\r
  85         on your development software.\r
  86 \r
  87   SMBus Logic options\r
  88   SMBus related APIs will not have any effect if in CoreI2C hardware\r
  89   configuration "Generate SMBus Logic" is not enabled. The APIs which will not\r
  90   give desired results in case SMBus Logic is disabled are:\r
  91   \r
  92       I2C_smbus_init()\r
  93       I2C_reset_smbus()\r
  94       I2C_enable_smbus_irq()\r
  95       I2C_disable_smbus_irq()\r
  96       I2C_suspend_smbus_slave()\r
  97       I2C_resume_smbus_slave()\r
  98       I2C_set_smsbus_alert()\r
  99       I2C_clear_smsbus_alert()\r
 100       I2C_get_irq_status() \r
 101 \r
 102   Fixed Baud Rate Values\r
 103   The serial clock frequency parameter passed to the I2C_init() and \r
 104   I2C_channel_init() functions may not have any effect if fixed values were\r
 105   selected for Baud rate in the hardware configuration of CoreI2C. When fixed\r
 106   values are selected for these baud rates, the driver cannot overwrite\r
 107   the fixed values.\r
 108 \r
 109   Fixed Slave Address Options Values\r
 110   The primary slave address  parameter passed to the I2C_init() function, and\r
 111   secondary address value passed to the I2C_set_slave_second_addr() function,\r
 112   may not have the desired effect if fixed values were selected for the slave 0\r
 113   address and slave 1 address respectively. Proper operation of this version of\r
 114   the driver requires the slave addresses to be programmable.\r
 115 \r
 116   @section theory_op Theory of Operation\r
 117   The CoreI2C software driver is designed to allow the control of multiple\r
 118   instances of CoreI2C with one or more I2C channels. Each channel in an\r
 119   instance of CoreI2C in the hardware design is associated with a single \r
 120   instance of the i2c_instance_t structure in the software. You must allocate\r
 121   memory for one unique i2c_instance_t structure instance for each channel of\r
 122   each CoreI2C hardware instance. The contents of these data structures are\r
 123   initialised during calls to I2C_init() and if necessary I2C_channel_init().\r
 124   A pointer to the structure is passed to subsequent driver functions in order\r
 125   to identify the CoreI2C hardware instance and channel you wish to perform the\r
 126   requested operation.\r
 127 \r
 128   Note: Do not attempt to directly manipulate the contents of i2c_instance_t\r
 129        structures. These structures are only intended to be modified by the driver\r
 130        functions.\r
 131 \r
 132   The CoreI2C driver functions are grouped into the following categories:\r
 133     - Initialization and configuration functions\r
 134     - Interrupt control\r
 135     - I2C slave addressing functions\r
 136     - I2C master operations functions to handle write, read and write-read \r
 137       transactions\r
 138     - I2C slave operations functions to handle write, read and write-read \r
 139       transactions\r
 140     - Mixed master-slave operations \r
 141     - SMBus interface configuration and control.\r
 142     \r
 143   Initialization and Configuration\r
 144     The CoreI2C device is first initialized through a call to the I2C_init()\r
 145     function. Since each CoreI2C peripheral supports up to 16 channels, an\r
 146     additional function, I2C_channel_init(), is required to initialize the\r
 147     remaining channels with their own data structures.\r
 148 \r
 149     I2C_init() initializes channel 0 of a CoreI2C and the i2c_instance_t for\r
 150     channel 0 acts as the basis for further channel initialization as the\r
 151     hardware base address and I2C serial address are same across all the\r
 152     channels. I2C_init() must be called before any other  I2C driver function\r
 153     calls. The I2C_init() call for each CoreI2C takes the I2C serial address\r
 154     assigned to the I2C and the serial clock divider to be used to generate its\r
 155     I2C clock as configuration parameters. \r
 156     \r
 157     I2C_channel_init() takes as input parameters a pointer to the CoreI2C \r
 158     i2c_instance_t which has been initialized via I2C_init() and a pointer to a\r
 159     separate i2c_instance_t which represents this new channel. Another input\r
 160     parameter which is required by this function is serial clock divider which\r
 161     generates its I2C clock. \r
 162     \r
 163   Interrupt Control\r
 164     The CoreI2C driver is interrupt driven and it uses each channels INT\r
 165     interrupt to drive the state machine which is at the heart of the driver.\r
 166     The application is responsible for providing the link between the interrupt\r
 167     generating hardware and the CoreI2C interrupt handler and must ensure that\r
 168     the I2C_isr() function is called with the correct i2c_instance_t structure\r
 169     pointer for the CoreI2C channel initiating the interrupt.\r
 170     \r
 171     The driver enables and disables the generation of INT interrupts by CoreI2C\r
 172     at various times when it is operating through the user supplied\r
 173     I2C_enable_irq() and I2C_disable_irq() functions. \r
 174     \r
 175     The function I2C_register_write_handler() is used to register a write\r
 176     handler function with the CoreI2C driver which is called on completion\r
 177     of an I2C write transaction by the CoreI2C slave. It is the user\r
 178     applications responsibility to create and register the implementation of\r
 179     this handler function that processes or triggers the processing of the\r
 180     received data. \r
 181     \r
 182     The other two interrupt sources in the CoreI2C, are related to SMBus\r
 183     operation and are enabled and disabled through I2C_enable_smbus_irq() and\r
 184     I2C_disable_smbus_irq() respectively. Due to the application specific\r
 185     nature of the response to SMBus interrupts, you must design interrupt\r
 186     handler functions in the application to get the desired behaviour for\r
 187     SMBus related interrupts.\r
 188     \r
 189     If enabled, the SMBA_INT signal from the CoreI2C is asserted if an\r
 190     SMBALERT condition is signalled on the SMBALERT_NI input for the channel.\r
 191     \r
 192     If enabled, the SMBS_INT signal from the CoreI2C is asserted if an\r
 193     SMBSUSPEND condition is signalled on the SMBSUS_NI input for the channel.\r
 194 \r
 195   I2C slave addressing functions\r
 196     A CoreI2C peripheral can respond to three slave addresses:\r
 197     - Slave address 0 - This is the primary slave address which is used for\r
 198                         accessing a CoreI2C channel when it acts as a slave in\r
 199                         I2C transactions. You must configure the primary slave\r
 200                         address via I2C_init().\r
 201                         \r
 202     - Slave address 1 - This is the secondary slave address which might be\r
 203                         required in certain application specific scenarios.\r
 204                         The secondary slave address can be configured via\r
 205                         I2C_set_slave_second_addr() and disabled via \r
 206                         I2C_disable_slave_second_addr().\r
 207                         \r
 208     - General call address - A CoreI2C slave can be configured to respond to\r
 209                         a broadcast command by a master transmitting the\r
 210                         general call address of 0x00. Use the I2C_set_gca()\r
 211                         function to enable the slave to respond to the general\r
 212                         call address. If the CoreI2C slave is not required to\r
 213                         respond to the general call address, disable this\r
 214                         address by calling I2C_clear_gca().\r
 215 \r
 216     Note: All channels on a CoreI2C instance share the same slave address logic.\r
 217           This means that they cannot have separate slave addresses and rely on\r
 218           the separate physical I2C bus connections to distinguish them.\r
 219           \r
 220   Transaction Types\r
 221     The I2C driver is designed to handle three types of I2C transaction:\r
 222       Write transactions\r
 223       Read transactions\r
 224       Write-read transactions\r
 225  \r
 226     Write transaction\r
 227       The master I2C device initiates a write transaction by sending a START bit\r
 228       as soon as the bus becomes free. The START bit is followed by the 7-bit\r
 229       serial address of the target slave device followed by the read/write bit\r
 230       indicating the direction of the transaction. The slave acknowledges the\r
 231       receipt of it's address with an acknowledge bit. The master sends data one\r
 232       byte at a time to the slave, which must acknowledge receipt of each byte\r
 233       for the next byte to be sent. The master sends a STOP bit to complete the\r
 234       transaction. The slave can abort the transaction by replying with a \r
 235       non-acknowledge bit instead of an acknowledge.\r
 236       \r
 237       The application programmer can choose not to send a STOP bit at the end of\r
 238       the transaction causing the next transaction to begin with a repeated \r
 239       START bit.\r
 240       \r
 241     Read transaction\r
 242       The master I2C device initiates a read transaction by sending a START bit\r
 243       as soon as the bus becomes free. The START bit is followed by the 7-bit\r
 244       serial address of the target slave device followed by the read/write bit\r
 245       indicating the direction of the transaction. The slave acknowledges\r
 246       receipt of it's slave address with an acknowledge bit. The slave sends\r
 247       data one byte at a time to the master, which must acknowledge receipt of\r
 248       each byte for the next byte to be sent. The master sends a non-acknowledge\r
 249       bit following the last byte it wishes to read followed by a STOP bit.\r
 250       \r
 251       The application programmer can choose not to send a STOP bit at the end of\r
 252       the transaction causing the next transaction to begin with a repeated \r
 253       START bit.\r
 254  \r
 255     Write-read transaction\r
 256       The write-read transaction is a combination of a write transaction\r
 257       immediately followed by a read transaction. There is no STOP bit between\r
 258       the write and read phases of a write-read transaction. A repeated START\r
 259       bit is sent between the write and read phases.\r
 260       \r
 261       Whilst the write handler is being executed, the slave holds the clock line\r
 262       low to stretch the clock until the response is ready.\r
 263       \r
 264       The write-read transaction is typically used to send a command or offset\r
 265       in the write transaction specifying the logical data to be transferred\r
 266       during the read phase.\r
 267       \r
 268       The application programmer can choose not to send a STOP bit at the end of\r
 269       the transaction causing the next transaction to begin with a repeated\r
 270       START bit.\r
 271 \r
 272   Master Operations\r
 273     The application can use the I2C_write(), I2C_read() and I2C_write_read()\r
 274     functions to initiate an I2C bus transaction. The application can then wait\r
 275     for the transaction to complete using the I2C_wait_complete() function\r
 276     or poll the status of the I2C transaction using the I2C_get_status()\r
 277     function until it returns a value different from I2C_IN_PROGRESS. The\r
 278     I2C_system_tick() function can be used to set a time base for the\r
 279     I2C_wait_complete() function\92s time out delay.\r
 280 \r
 281   Slave Operations\r
 282     The configuration of the  I2C driver to operate as an I2C slave requires\r
 283     the use of the following functions:\r
 284        I2C_set_slave_tx_buffer()\r
 285        I2C_set_slave_rx_buffer()\r
 286        I2C_set_slave_mem_offset_length()\r
 287        I2C_register_write_handler()\r
 288        I2C_enable_slave()\r
 289        \r
 290     Use of all functions is not required if the slave I2C does not need to support\r
 291     all types of I2C read transactions. The subsequent sections list the functions\r
 292     that must be used to support each transaction type. \r
 293     \r
 294     Responding to read transactions\r
 295       The following functions are used to configure the  CoreI2C driver to\r
 296       respond to I2C read transactions:\r
 297         I2C_set_slave_tx_buffer()\r
 298         I2C_enable_slave()\r
 299         \r
 300       The function I2C_set_slave_tx_buffer() specifies the data buffer that\r
 301       will be transmitted when the I2C slave is the target of an I2C read\r
 302       transaction. It is then up to the application to manage the content of\r
 303       that buffer to control the data that will be transmitted to the I2C\r
 304       master as a result of the read transaction.\r
 305       \r
 306       The function I2C_enable_slave() enables the  I2C hardware instance\r
 307       to respond to I2C transactions. It must be called after the  I2C driver\r
 308       has been configured to respond to the required transaction types.\r
 309 \r
 310     Responding to write transactions\r
 311       The following functions are used to configure the  I2C driver to respond\r
 312       to I2C write transactions:\r
 313         I2C_set_slave_rx_buffer()\r
 314         I2C_register_write_handler()\r
 315         I2C_enable_slave()\r
 316         \r
 317       The function I2C_set_slave_rx_buffer() specifies the data buffer that\r
 318       will be used to store the data received by the I2C slave when it is the\r
 319       target an I2C  write transaction.\r
 320       \r
 321       The function I2C_register_write_handler() specifies the handler function\r
 322       that must be called on completion of the I2C write transaction. It is this\r
 323       handler function that processes or triggers the processing of the received\r
 324       data.\r
 325       \r
 326       The function I2C_enable_slave() enables the  I2C hardware instance\r
 327       to respond to I2C transactions. It must be called after the  I2C driver\r
 328       has been configured to respond to the required transaction types.\r
 329 \r
 330     Responding to write-read transactions\r
 331       The following functions are used to configure the CoreI2C driver to \r
 332       respond to write-read transactions:\r
 333         I2C_set_slave_mem_offset_length()\r
 334         I2C_set_slave_tx_buffer()\r
 335         I2C_set_slave_rx_buffer()\r
 336         I2C_register_write_handler()\r
 337         I2C_enable_slave()\r
 338         \r
 339       The function I2C_set_slave_mem_offset_length() specifies the number of\r
 340       bytes expected by the I2C slave during the write phase of the write-read\r
 341       transaction.\r
 342       \r
 343       The function I2C_set_slave_tx_buffer() specifies the data that will be\r
 344       transmitted to the I2C master during the read phase of the write-read\r
 345       transaction. The value received by the I2C slave during the write phase of\r
 346       the transaction will be used as an index into the transmit buffer\r
 347       specified by this function to decide which part of the transmit buffer\r
 348       will be transmitted to the I2C master as part of the read phase of the\r
 349       write-read transaction. \r
 350       \r
 351       The function I2C_set_slave_rx_buffer() specifies the data buffer that\r
 352       will be used to store the data received by the I2C slave during the write\r
 353       phase of the write-read transaction. This buffer must be at least large\r
 354       enough to accommodate the number of bytes specified through the\r
 355       I2C_set_slave_mem_offset_length() function.\r
 356       \r
 357       The function I2C_register_write_handler() can optionally be used to\r
 358       specify a handler function that is called on completion of the write phase\r
 359       of the I2C write-read transaction. If a handler function is registered, it\r
 360       is responsible for processing the received data in the slave receive\r
 361       buffer and populating the slave transmit buffer with the data that will be\r
 362       transmitted to the I2C master as part of the read phase of the write-read\r
 363       transaction.\r
 364       \r
 365       The function I2C_enable_slave() enables the CoreI2C hardware instance to \r
 366       respond to I2C transactions. It must be called after the CoreI2C driver\r
 367       has been configured to respond to the required transaction types.\r
 368 \r
 369   Mixed Master-Slave Operations\r
 370     The CoreI2C device supports mixed master and slave operations. If the \r
 371     CoreI2C slave has a transaction in progress and your application attempts to\r
 372     begin a master mode transaction, the CoreI2C driver queu3es the master mode\r
 373     transaction until the bus is released and the CoreI2C can switch to master\r
 374     mode and acquire the bus. The CoreI2C master then starts the previously\r
 375     queued master transaction.\r
 376     \r
 377   SMBus Control\r
 378     The CoreI2C driver enables the CoreI2C peripheral\92s SMBus functionality\r
 379     using the I2C_smbus_init() function.\r
 380     \r
 381     The I2C_suspend_smbus_slave() function is used, with a master mode CoreI2C,\r
 382     to force slave devices on the SMBus to enter their power-down/suspend mode.\r
 383     The I2C_resume_smbus_slave() function is used to end the suspend operation\r
 384     on the SMBus.\r
 385     \r
 386     The I2C_reset_smbus() function is used, with a master mode CoreI2C, to force\r
 387     all devices on the SMBus to reset their SMBUs interface.\r
 388     \r
 389     The I2C_set_smsbus_alert() function is used, by a slave mode CoreI2C, to\r
 390     force communication with the SMBus master. Once communications with the\r
 391     master is initiated, the I2C_clear_smsbus_alert() function is used to clear\r
 392     the alert condition.\r
 393     \r
 394     The I2C_enable_smbus_irq() and I2C_disable_smbus_irq() functions are used to\r
 395     enable and disable the SMBSUS and SMBALERT SMBus interrupts.\r
 396 \r
 397  *//*=========================================================================*/\r
 398 \r
 399 #ifndef CORE_I2C_H_\r
 400 #define CORE_I2C_H_\r
 401 \r
 402 #include "cpu_types.h"\r
 403 #ifdef __cplusplus\r
 404 extern "C" {\r
 405 #endif \r
 406 \r
 407 /*-------------------------------------------------------------------------*//**\r
 408   The I2C_RELEASE_BUS constant is used to specify the options parameter to\r
 409   functions I2C_read(), I2C_write() and I2C_write_read() to indicate\r
 410   that a STOP bit must be generated at the end of the I2C transaction to release\r
 411   the bus.\r
 412  */\r
 413 #define I2C_RELEASE_BUS     0x00u\r
 414 \r
 415 /*-------------------------------------------------------------------------*//**\r
 416   The I2C_HOLD_BUS constant is used to specify the options parameter to\r
 417   functions I2C_read(), I2C_write() and I2C_write_read() to indicate\r
 418   that a STOP bit must not be generated at the end of the I2C transaction in\r
 419   order to retain the bus ownership. This causes the next transaction to\r
 420   begin with a repeated START bit and no STOP bit between the transactions.\r
 421  */\r
 422 #define I2C_HOLD_BUS        0x01u\r
 423 \r
 424 /*-------------------------------------------------------------------------*//**\r
 425   The following constants specify the interrupt identifier number which will be\r
 426   solely used by driver API. This has nothing to do with hardware interrupt line.\r
 427   I2C_INT_IRQ is the primary interrupt signal which drives the state machine\r
 428   of the CoreI2C driver. The I2C_SMBALERT_IRQ and I2C_SMBUS_IRQ are used by\r
 429   SMBus interrupt enable and disable functions. These IRQ numbers are also used\r
 430   by I2C_get_irq_status().\r
 431  */\r
 432 #define I2C_NO_IRQ             0x00u\r
 433 #define I2C_SMBALERT_IRQ       0x01u\r
 434 #define I2C_SMBSUS_IRQ         0x02u\r
 435 #define I2C_INTR_IRQ           0x04u\r
 436 \r
 437 /*-------------------------------------------------------------------------*//**\r
 438   The I2C_NO_TIMEOUT constant is used as parameter to the I2C_wait_complete()\r
 439   function to indicate that the wait for completion of the transaction should\r
 440   not time out.\r
 441  */\r
 442 #define I2C_NO_TIMEOUT  0u\r
 443 \r
 444 /*-------------------------------------------------------------------------*//**\r
 445   The i2c_channel_number_t type is used to specify the channel number of a\r
 446   CoreI2C instance.\r
 447  */\r
 448 typedef enum i2c_channel_number {\r
 449     I2C_CHANNEL_0 = 0u,\r
 450     I2C_CHANNEL_1,\r
 451     I2C_CHANNEL_2,\r
 452     I2C_CHANNEL_3,\r
 453     I2C_CHANNEL_4,\r
 454     I2C_CHANNEL_5,\r
 455     I2C_CHANNEL_6,\r
 456     I2C_CHANNEL_7,\r
 457     I2C_CHANNEL_8,\r
 458     I2C_CHANNEL_9,\r
 459     I2C_CHANNEL_10,\r
 460     I2C_CHANNEL_11,\r
 461     I2C_CHANNEL_12,\r
 462     I2C_CHANNEL_13,\r
 463     I2C_CHANNEL_14,\r
 464     I2C_CHANNEL_15,\r
 465     I2C_MAX_CHANNELS = 16u\r
 466 } i2c_channel_number_t;\r
 467 \r
 468 /*-------------------------------------------------------------------------*//**\r
 469   The i2c_clock_divider_t type is used to specify the divider to be applied\r
 470   to the I2C PCLK or BCLK signal in order to generate the I2C clock.\r
 471   The I2C_BCLK_DIV_8 value selects a clock frequency based on division of BCLK,\r
 472   all other values select a clock frequency based on division of PCLK.\r
 473  */\r
 474 typedef enum i2c_clock_divider {\r
 475     I2C_PCLK_DIV_256 = 0u,\r
 476     I2C_PCLK_DIV_224,\r
 477     I2C_PCLK_DIV_192,\r
 478     I2C_PCLK_DIV_160,\r
 479     I2C_PCLK_DIV_960,\r
 480     I2C_PCLK_DIV_120,\r
 481     I2C_PCLK_DIV_60,\r
 482     I2C_BCLK_DIV_8\r
 483 } i2c_clock_divider_t;\r
 484 \r
 485 /*-------------------------------------------------------------------------*//**\r
 486   The i2c_status_t type is used to report the status of I2C transactions.\r
 487  */\r
 488 typedef enum i2c_status\r
 489 {\r
 490     I2C_SUCCESS = 0u,\r
 491     I2C_IN_PROGRESS,\r
 492     I2C_FAILED,\r
 493     I2C_TIMED_OUT\r
 494 } i2c_status_t;\r
 495 \r
 496 /*-------------------------------------------------------------------------*//**\r
 497   The i2c_slave_handler_ret_t type is used by slave write handler functions\r
 498   to indicate whether or not the received data buffer should be released.\r
 499  */\r
 500 typedef enum i2c_slave_handler_ret {\r
 501     I2C_REENABLE_SLAVE_RX = 0u,\r
 502     I2C_PAUSE_SLAVE_RX = 1u\r
 503 } i2c_slave_handler_ret_t;\r
 504 \r
 505 typedef struct i2c_instance i2c_instance_t ;\r
 506 \r
 507 /*-------------------------------------------------------------------------*//**\r
 508   Slave write handler functions prototype.\r
 509   ------------------------------------------------------------------------------\r
 510   This defines the function prototype that must be followed by  I2C slave write\r
 511   handler functions. These functions are registered with the CoreI2C driver\r
 512   through the I2C_register_write_handler() function.\r
 513 \r
 514   Declaring and Implementing Slave Write Handler Functions:\r
 515     Slave write handler functions should follow the following prototype:\r
 516     i2c_slave_handler_ret_t write_handler\r
 517     ( \r
 518         i2c_instance_t *instance, uint8_t * data, uint16_t size \r
 519     );\r
 520 \r
 521     The instance parameter is a pointer to the i2c_instance_t for which this\r
 522     slave write handler has been declared.\r
 523     \r
 524     The data parameter is a pointer to a buffer (received data buffer) holding\r
 525     the data written to the I2C slave.\r
 526     \r
 527     Defining the macro INCLUDE_SLA_IN_RX_PAYLOAD causes the driver to insert the\r
 528     actual address used to access the slave as the first byte in the buffer.\r
 529     This allows applications tailor their response based on the actual address\r
 530     used to access the slave (primary address, secondary address or GCA).\r
 531     \r
 532     The size parameter is the number of bytes held in the received data buffer.\r
 533     Handler functions must return one of the following values:\r
 534         I2C_REENABLE_SLAVE_RX\r
 535         I2C_PAUSE_SLAVE_RX.\r
 536         \r
 537     If the handler function returns I2C_REENABLE_SLAVE_RX, the driver releases\r
 538     the received data buffer and allows further I2C write transactions to the\r
 539     I2C slave to take place.\r
 540     \r
 541     If the handler function returns I2C_PAUSE_SLAVE_RX, the I2C slave responds\r
 542     to subsequent write requests with a non-acknowledge bit (NACK), until the\r
 543     received data buffer content has been processed by some other part of the\r
 544     software application.\r
 545     \r
 546     A call to I2C_enable_slave() is required at some point after returning\r
 547     I2C_PAUSE_SLAVE_RX in order to release the received data buffer so it can\r
 548     be used to store data received by subsequent I2C write transactions.\r
 549  */\r
 550 typedef i2c_slave_handler_ret_t (*i2c_slave_wr_handler_t)(i2c_instance_t *instance, uint8_t *, uint16_t );\r
 551 \r
 552 \r
 553 /*-------------------------------------------------------------------------*//**\r
 554   i2c_instance_t\r
 555   ------------------------------------------------------------------------------\r
 556   This structure is used to identify the various CoreI2C hardware instances in\r
 557   your system and the I2C channels within them. Your application software should\r
 558   declare one instance of this structure for each channel of each instance of\r
 559   CoreI2C in your system. The functions I2C_init() and I2C_channel_init() \r
 560   initialize this structure depending on whether it is channel 0 or one of the\r
 561   additional channels respectively. A pointer to an initialized instance of the\r
 562   structure should be passed as the first parameter to the CoreI2C driver\r
 563   functions, to identify which CoreI2C hardware instance and channel should\r
 564   perform the requested operation.\r
 565   \r
 566   The contents of this data structure should not be modified or used outside of\r
 567   the CoreI2C driver. Software using the CoreI2C driver should only need to \r
 568   create one single instance of this data structure for each channel of each \r
 569   CoreI2C hardware instance in the system then pass a pointer to these data\r
 570   structures with each call to the CoreI2C driver in order to identify the\r
 571   CoreI2C hardware instance it wishes to use.\r
 572  */\r
 573 struct i2c_instance\r
 574 {\r
 575     addr_t base_address;\r
 576     uint_fast8_t ser_address;\r
 577 \r
 578     /* Transmit related info:*/\r
 579     uint_fast8_t target_addr;\r
 580 \r
 581     /* Current transaction type (WRITE, READ, RANDOM_READ)*/\r
 582     uint8_t transaction;\r
 583     \r
 584     uint_fast16_t random_read_addr;\r
 585 \r
 586     uint8_t options;\r
 587     \r
 588     /* Master TX INFO: */\r
 589     const uint8_t * master_tx_buffer;\r
 590     uint_fast16_t master_tx_size;\r
 591     uint_fast16_t master_tx_idx;\r
 592     uint_fast8_t dir;\r
 593     \r
 594     /* Master RX INFO: */\r
 595     uint8_t * master_rx_buffer;\r
 596     uint_fast16_t master_rx_size;\r
 597     uint_fast16_t master_rx_idx;\r
 598 \r
 599     /* Master Status */\r
 600     volatile i2c_status_t master_status;\r
 601     uint32_t master_timeout_ms;\r
 602 \r
 603     /* Slave TX INFO */\r
 604     const uint8_t * slave_tx_buffer;\r
 605     uint_fast16_t slave_tx_size;\r
 606     uint_fast16_t slave_tx_idx;\r
 607     \r
 608     /* Slave RX INFO */\r
 609     uint8_t * slave_rx_buffer;\r
 610     uint_fast16_t slave_rx_size;\r
 611     uint_fast16_t slave_rx_idx;\r
 612     /* Slave Status */\r
 613     volatile i2c_status_t slave_status;\r
 614     \r
 615     /* Slave data: */\r
 616     uint_fast8_t slave_mem_offset_length;\r
 617     i2c_slave_wr_handler_t slave_write_handler;\r
 618     uint8_t is_slave_enabled;\r
 619     \r
 620     /* user  specific data */\r
 621     void *p_user_data ;\r
 622 \r
 623     /* I2C bus status */\r
 624     uint8_t bus_status;\r
 625 \r
 626     /* Is transaction pending flag */\r
 627     uint8_t is_transaction_pending;\r
 628 \r
 629     /* I2C Pending transaction */\r
 630     uint8_t pending_transaction;\r
 631 };\r
 632 \r
 633 /*-------------------------------------------------------------------------*//**\r
 634   I2C initialization routine.\r
 635   ------------------------------------------------------------------------------\r
 636   The I2C_init() function is used to configure channel 0 of a CoreI2C instance.\r
 637   It sets the base hardware address which is used to locate the CoreI2C instance\r
 638   in memory and also used internally by I2C_channel_init() to calculate the\r
 639   register addresses for any additional channels. The slave serial address set\r
 640   is shared by all channels on a CoreI2C instance. \r
 641   \r
 642   If only one channel is configured in a CoreI2C, the address of the \r
 643   i2c_instance_t used in I2C_Init() will also be used in subsequent calls to the\r
 644   CoreI2C driver functions. If more than one channel is configured in the\r
 645   CoreI2C, I2C_channel_init() will be called after I2C_init(), which initializes\r
 646   the i2c_instance_t data structure for a specific channel.\r
 647   ------------------------------------------------------------------------------\r
 648  @param this_i2c:\r
 649     Pointer to the i2c_instance_t data structure which will hold all data\r
 650     related to channel 0 of the CoreI2C instance being initialized. A pointer\r
 651     to this structure will be used in all subsequent calls to CoreI2C driver\r
 652     functions which are to operate on channel 0 of this CoreI2C instance.\r
 653   \r
 654   @param base_address:\r
 655     Base address in the processor's memory map of the registers of the CoreI2C\r
 656     instance being initialized.\r
 657  \r
 658   @param ser_address:\r
 659     This parameter sets the primary I2C serial address (SLAVE0 address) for the\r
 660     CoreI2C being initialized. It is the principal I2C bus address to which the\r
 661     CoreI2C instance will respond. CoreI2C can operate in master mode or slave\r
 662     mode and the serial address is significant only in the case of I2C slave\r
 663     mode. In master mode, CoreI2C does not require a serial address and the\r
 664     value of this parameter is not important. If you do not intend to use the\r
 665     CoreI2C device in slave mode, then any dummy slave address value can be\r
 666     provided to this parameter. However, in systems where the CoreI2C may be\r
 667     expected to switch from master mode to slave mode, it is advisable to\r
 668     initialize the CoreI2C device with a valid serial slave address.\r
 669     \r
 670     You need to call the I2C_init() function whenever it is required to change \r
 671     the primary slave address as there is no separate function to set the\r
 672     primary slave address of the I2C device. The serial address being\r
 673     initialized through this function is basically the primary slave address or\r
 674     slave address0. I2C_set_slave_second_addr() can be used to set the\r
 675     secondary slave address or slave address 1.\r
 676     Note : ser_address parameter does not have any affect if fixed slave \r
 677            address is enabled in CoreI2C hardware design. CoreI2C will \r
 678            be always addressed with the hardware configured fixed slave\r
 679            address.\r
 680     Note : ser_address parameter will not have any affect if the CoreI2C\r
 681            instance is only used in master mode.\r
 682 \r
 683   @param ser_clock_speed:\r
 684     This parameter sets the I2C serial clock frequency. It selects the divider\r
 685     that will be used to generate the serial clock from the APB PCLK or from\r
 686     the BCLK. It can be one of the following:\r
 687         I2C_PCLK_DIV_256\r
 688         I2C_PCLK_DIV_224\r
 689         I2C_PCLK_DIV_192\r
 690         I2C_PCLK_DIV_160\r
 691         I2C_PCLK_DIV_960\r
 692         I2C_PCLK_DIV_120\r
 693         I2C_PCLK_DIV_60\r
 694         I2C_BCLK_DIV_8\r
 695     Note: serial_clock_speed value will have no affect if Fixed baud rate is \r
 696           enabled in CoreI2C hardware instance configuration dialogue window. \r
 697           The fixed baud rate divider value will override the value\r
 698           passed as parameter in this function.\r
 699     Note: serial_clock_speed value is not critical for devices that only operate\r
 700           as slaves and can be set to any of the above values.  \r
 701 \r
 702   @return none.  \r
 703   \r
 704   Example:\r
 705   @code\r
 706     #define COREI2C_BASE_ADDR  0xC0000000u\r
 707     #define COREI2C_SER_ADDR   0x10u\r
 708 \r
 709     i2c_instance_t g_i2c_inst;\r
 710 \r
 711     void system_init( void )\r
 712     {\r
 713         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, COREI2C_SER_ADDR,\r
 714                   I2C_PCLK_DIV_256 );\r
 715     }\r
 716   @endcode\r
 717  */\r
 718 void I2C_init\r
 719 (\r
 720     i2c_instance_t * this_i2c,\r
 721     addr_t base_address,\r
 722     uint8_t ser_address,\r
 723     i2c_clock_divider_t ser_clock_speed\r
 724 );\r
 725 \r
 726 /*-------------------------------------------------------------------------*//**\r
 727   I2C channel initialization routine.\r
 728   ------------------------------------------------------------------------------\r
 729   The I2C_channel_init() function initializes and configures hardware and data\r
 730   structures of one of the additional channels of a CoreI2C instance.\r
 731   I2C_init() must be called before calling this function to set the CoreI2C\r
 732   instance hardware base address and I2C serial address. I2C_channel_init() also\r
 733   initializes I2C serial clock divider to set the serial clock baud rate.  \r
 734   The pointer to data structure i2c_instance_t used for a particular channel\r
 735   will be used as an input parameter to subsequent CoreI2C driver functions\r
 736   which operate on this channel.\r
 737   ------------------------------------------------------------------------------\r
 738   @param this_i2c_channel\r
 739     Pointer to the i2c_instance_t data structure holding all data related to the\r
 740     CoreI2C channel being initialized. A pointer to the same data structure will\r
 741     be used in subsequent calls to the CoreI2C driver functions in order to\r
 742     identify the CoreI2C channel instance that should perform the operation \r
 743     implemented by the called driver function.\r
 744 \r
 745   @param this_i2c:\r
 746     This is a pointer to an i2c_instance_t structure previously initialized by\r
 747     I2C_init(). It holds information regarding the hardware base address and\r
 748     I2C serial address for the CoreI2C containing the channel to be\r
 749     initialized. This information is required by I2C_channel_init() to\r
 750     initialize the i2c_instance_t structure pointed to by this_i2c_channel as\r
 751     all channels in a CoreI2C instance share the same base address and serial\r
 752     address. It is very important that the i2c_instance_t structure pointed to\r
 753     by this_i2c has been previously initialized with a call to I2C_init().\r
 754     \r
 755   @param channel_number:\r
 756     This parameter of type i2c_channel_number_t identifies the channel to be\r
 757     initialized.\r
 758 \r
 759   @param ser_clock_speed:\r
 760     This parameter sets the I2C serial clock frequency. It selects the divider\r
 761     that will be used to generate the serial clock from the APB PCLK or from\r
 762     the BCLK. It can be one of the following:\r
 763         I2C_PCLK_DIV_256\r
 764         I2C_PCLK_DIV_224\r
 765         I2C_PCLK_DIV_192\r
 766         I2C_PCLK_DIV_160\r
 767         I2C_PCLK_DIV_960\r
 768         I2C_PCLK_DIV_120\r
 769         I2C_PCLK_DIV_60\r
 770         I2C_BCLK_DIV_8\r
 771     \r
 772     Note: serial_clock_speed value will have no affect if Fixed baud rate is \r
 773           enabled in CoreI2C hardware instance configuration dialogue window. \r
 774           The fixed baud rate divider value will supersede the value \r
 775           passed as parameter in this function.\r
 776 \r
 777     Note: ser_clock_speed value is not critical for devices that only operate\r
 778           as slaves and can be set to any of the above values.  \r
 779   @return none.  \r
 780   \r
 781   Example:\r
 782   @code\r
 783     #define COREI2C_BASE_ADDR  0xC0000000u\r
 784     #define COREI2C_SER_ADDR   0x10u\r
 785     #define DATA_LENGTH        16u\r
 786 \r
 787     i2c_instance_t g_i2c_inst;\r
 788     i2c_instance_t g_i2c_channel_1_inst;\r
 789 \r
 790     uint8_t  tx_buffer[DATA_LENGTH];\r
 791     uint8_t  write_length = DATA_LENGTH;\r
 792 \r
 793     void system_init( void )\r
 794     {\r
 795         uint8_t  target_slave_addr = 0x12;\r
 796         \r
 797         // Initialize base CoreI2C instance\r
 798         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, COREI2C_SER_ADDR,\r
 799                   I2C_PCLK_DIV_256 );\r
 800         \r
 801         // Initialize CoreI2C channel 1 with different clock speed\r
 802         I2C_channel_init( &g_i2c_channel_1_inst, &g_i2c_inst, I2C_CHANNEL_1,\r
 803                           I2C_PCLK_DIV_224 );\r
 804         \r
 805         // Write data to Channel 1 of CoreI2C instance.\r
 806         I2C_write( &g_i2c_channel_1_inst, target_slave_addr, tx_buffer,\r
 807                    write_length, I2C_RELEASE_BUS );\r
 808     }\r
 809   @endcode\r
 810           \r
 811 */\r
 812 void I2C_channel_init\r
 813 (\r
 814     i2c_instance_t * this_i2c_channel,\r
 815     i2c_instance_t * this_i2c,\r
 816     i2c_channel_number_t channel_number,\r
 817     i2c_clock_divider_t ser_clock_speed\r
 818 );\r
 819 \r
 820 /*------------------------------------------------------------------------------\r
 821   CoreI2C interrupt service routine.\r
 822   ------------------------------------------------------------------------------\r
 823     The function I2C_isr is the CoreI2C interrupt service routine. User must\r
 824     call this function from their application level CoreI2C interrupt handler\r
 825     function. This function runs the I2C state machine based on previous and \r
 826     current status.\r
 827   ------------------------------------------------------------------------------\r
 828     @param this_i2c:\r
 829     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
 830     holding all data related to a specific CoreI2C channel. For example, if only\r
 831     one channel is initialized, this data structure holds the information of \r
 832     channel 0 of the instantiated CoreI2C hardware.\r
 833     \r
 834     @return none\r
 835     \r
 836     Example:\r
 837     @code\r
 838     \r
 839     #define COREI2C_BASE_ADDR  0xC0000000u\r
 840     #define COREINTERRUPT_BASE_ADDR  0xCC000000u\r
 841     #define COREI2C_SER_ADDR   0x10u\r
 842     #define I2C_IRQ_NB           2u\r
 843     \r
 844     i2c_instance_t g_i2c_inst;\r
 845 \r
 846     void core_i2c_isr( void )\r
 847     {\r
 848        I2C_isr( &g_i2c_inst );\r
 849     }\r
 850     \r
 851    void main( void )\r
 852     {\r
 853         CIC_init( COREINTERRUPT_BASE_ADDR );\r
 854         NVIC_init();\r
 855         CIC_set_irq_handler( I2C_IRQ_NB, core_i2c_isr );\r
 856         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, COREI2C_SER_ADDR,\r
 857                   I2C_PCLK_DIV_256 );\r
 858         NVIC_enable_interrupt( NVIC_IRQ_0 );\r
 859     }\r
 860     @endcode\r
 861  */\r
 862 void I2C_isr\r
 863 (\r
 864     i2c_instance_t * this_i2c\r
 865 );\r
 866 \r
 867 /*******************************************************************************\r
 868  *******************************************************************************\r
 869  * \r
 870  *                           Master specific functions\r
 871  * \r
 872  * The following functions are only used within an I2C master's implementation.\r
 873  */\r
 874  \r
 875 /*-------------------------------------------------------------------------*//**\r
 876   I2C master write function.\r
 877   ------------------------------------------------------------------------------\r
 878   This function initiates an I2C master write transaction. This function returns\r
 879   immediately after initiating the transaction. The content of the write buffer\r
 880   passed as parameter should not be modified until the write transaction\r
 881   completes. It also means that the memory allocated for the write buffer should\r
 882   not be freed or should not go out of scope before the write completes. You can\r
 883   check for the write transaction completion using the I2C_status() function.\r
 884   ------------------------------------------------------------------------------\r
 885   @param this_i2c:\r
 886     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
 887     holding all data related to a specific CoreI2C channel. For example, if only\r
 888     one channel is initialized, this data structure holds the information of \r
 889     channel 0 of the instantiated CoreI2C hardware.\r
 890 \r
 891   @param serial_addr:\r
 892     This parameter specifies the serial address of the target I2C device.\r
 893   \r
 894   @param write_buffer:\r
 895     This parameter is a pointer to a buffer holding the data to be written to\r
 896     the target I2C device.\r
 897     Care must be taken not to release the memory used by this buffer before the\r
 898     write transaction completes. For example, it is not appropriate to return\r
 899     from a function allocating this buffer as an auto array variable before the\r
 900     write transaction completes as this would result in the buffer's memory \r
 901     being de-allocated from the stack when the function returns. This memory\r
 902     could then be subsequently reused and modified causing unexpected data to \r
 903     be written to the target I2C device.\r
 904   \r
 905   @param write_size:\r
 906     Number of bytes held in the write_buffer to be written to the target I2C\r
 907     device.\r
 908  \r
 909   @param options:\r
 910     The options parameter is used to indicate if the I2C bus should be released\r
 911     on completion of the write transaction. Using the I2C_RELEASE_BUS\r
 912     constant for the options parameter causes a STOP bit to be generated at the\r
 913     end of the write transaction causing the bus to be released for other I2C\r
 914     devices to use. Using the I2C_HOLD_BUS constant as options parameter\r
 915     prevents a STOP bit from being generated at the end of the write\r
 916     transaction, preventing other I2C devices from initiating a bus transaction.\r
 917   \r
 918   @return none.  \r
 919   \r
 920   Example:\r
 921   @code\r
 922     #define COREI2C_BASE_ADDR  0xC0000000u\r
 923     #define COREI2C_DUMMY_ADDR   0x10u\r
 924     #define DATA_LENGTH           16u\r
 925 \r
 926     i2c_instance_t g_i2c_inst;\r
 927 \r
 928     uint8_t  tx_buffer[DATA_LENGTH];\r
 929     uint8_t  write_length = DATA_LENGTH;     \r
 930 \r
 931     void main( void )\r
 932     {\r
 933         uint8_t  target_slave_addr = 0x12;\r
 934         i2c_status_t status;\r
 935         \r
 936         // Initialize base CoreI2C instance\r
 937         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, COREI2C_DUMMY_ADDR,\r
 938                   I2C_PCLK_DIV_256 );\r
 939         \r
 940         // Write data to Channel 0 of CoreI2C instance.\r
 941         I2C_write( &g_i2c_inst, target_slave_addr, tx_buffer, write_length,\r
 942                    I2C_RELEASE_BUS );\r
 943                    \r
 944         // Wait for completion and record the outcome\r
 945         status = I2C_wait_complete( &g_i2c_inst, I2C_NO_TIMEOUT );\r
 946     }\r
 947   @endcode\r
 948  */\r
 949 void I2C_write\r
 950 (\r
 951     i2c_instance_t * this_i2c,\r
 952     uint8_t serial_addr,\r
 953     const uint8_t * write_buffer,\r
 954     uint16_t write_size,\r
 955     uint8_t options\r
 956 );\r
 957 \r
 958 /*-------------------------------------------------------------------------*//**\r
 959   I2C master read.\r
 960   ------------------------------------------------------------------------------\r
 961   This function initiates an I2C master read transaction. This function returns\r
 962   immediately after initiating the transaction.\r
 963   The contents of the read buffer passed as parameter should not be modified\r
 964   until the read transaction completes. It also means that the memory allocated\r
 965   for the read buffer should not be freed or should not go out of scope before\r
 966   the read completes. You can check for the read transaction completion using \r
 967   the I2C_status() function.\r
 968   ------------------------------------------------------------------------------\r
 969   @param this_i2c:\r
 970     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
 971     holding all data related to a specific CoreI2C channel. For example, if only\r
 972     one channel is initialized, this data structure holds the information of \r
 973     channel 0 of the instantiated CoreI2C hardware.\r
 974   \r
 975   @param serial_addr:\r
 976     This parameter specifies the serial address of the target I2C device.\r
 977   \r
 978   @param read_buffer\r
 979     This is a pointer to a buffer where the data received from the target device\r
 980     will be stored.\r
 981     Care must be taken not to release the memory used by this buffer before the\r
 982     read transaction completes. For example, it is not appropriate to return\r
 983     from a function allocating this buffer as an auto array variable before the\r
 984     read transaction completes as this would result in the buffer's memory being\r
 985     de-allocated from the stack when the function returns. This memory could\r
 986     then be subsequently reallocated resulting in the read transaction\r
 987     corrupting the newly allocated memory. \r
 988 \r
 989   @param read_size:\r
 990     This parameter specifies the number of bytes to read from the target device.\r
 991     This size must not exceed the size of the read_buffer buffer.\r
 992  \r
 993   @param options:\r
 994     The options parameter is used to indicate if the I2C bus should be released\r
 995     on completion of the read transaction. Using the I2C_RELEASE_BUS\r
 996     constant for the options parameter causes a STOP bit to be generated at the\r
 997     end of the read transaction causing the bus to be released for other I2C\r
 998     devices to use. Using the I2C_HOLD_BUS constant as options parameter\r
 999     prevents a STOP bit from being generated at the end of the read transaction,\r
1000     preventing other I2C devices from initiating a bus transaction.\r
1001     \r
1002   @return none.  \r
1003   \r
1004   Example:\r
1005   @code\r
1006     #define COREI2C_BASE_ADDR  0xC0000000u\r
1007     #define COREI2C_DUMMY_ADDR   0x10u\r
1008     #define DATA_LENGTH           16u\r
1009 \r
1010     i2c_instance_t g_i2c_inst;\r
1011 \r
1012     uint8_t  rx_buffer[DATA_LENGTH];\r
1013     uint8_t  read_length = DATA_LENGTH;     \r
1014 \r
1015     void main( void )\r
1016     {\r
1017         uint8_t  target_slave_addr = 0x12;\r
1018         i2c_status_t status;\r
1019         \r
1020         // Initialize base CoreI2C instance\r
1021         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, COREI2C_DUMMY_ADDR,\r
1022                   I2C_PCLK_DIV_256 );\r
1023         \r
1024         // Read data from target slave Channel 0 of CoreI2C instance.\r
1025         I2C_read( &g_i2c_inst, target_slave_addr, rx_buffer, read_length,\r
1026                   I2C_RELEASE_BUS );\r
1027         \r
1028         status = I2C_wait_complete( &g_i2c_inst, I2C_NO_TIMEOUT );\r
1029     }\r
1030   @endcode\r
1031  */\r
1032 void I2C_read\r
1033 (\r
1034     i2c_instance_t * this_i2c,\r
1035     uint8_t serial_addr,\r
1036     uint8_t * read_buffer,\r
1037     uint16_t read_size,\r
1038     uint8_t options\r
1039 );\r
1040 \r
1041 /*-------------------------------------------------------------------------*//**\r
1042   I2C master write-read\r
1043   ------------------------------------------------------------------------------\r
1044   This function initiates an I2C write-read transaction where data is first\r
1045   written to the target device before issuing a restart condition and changing\r
1046   the direction of the I2C transaction in order to read from the target device.\r
1047   \r
1048   The same warnings about buffer allocation in I2C_write() and I2C_read() \r
1049   apply to this function.\r
1050   ------------------------------------------------------------------------------\r
1051   @param this_i2c:\r
1052     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1053     holding all data related to a specific CoreI2C channel. For example, if only\r
1054     one channel is initialized, this data structure holds the information of\r
1055     channel 0 of the instantiated CoreI2C hardware.\r
1056   \r
1057   @param serial_addr:\r
1058     This parameter specifies the serial address of the target I2C device.\r
1059   \r
1060   @param addr_offset:\r
1061     This parameter is a pointer to the buffer containing the data that will be\r
1062     sent to the slave during the write phase of the write-read transaction. This\r
1063     data is typically used to specify an address offset specifying to the I2C\r
1064     slave device what data it must return during the read phase of the\r
1065     write-read transaction.\r
1066   \r
1067   @param offset_size:\r
1068     This parameter specifies the number of offset bytes to be written during the\r
1069     write phase of the write-read transaction. This is typically the size of the\r
1070     buffer pointed to by the addr_offset parameter.\r
1071   \r
1072   @param read_buffer:\r
1073     This parameter is a pointer to the buffer where the data read from the I2C\r
1074     slave will be stored.\r
1075   \r
1076   @param read_size:\r
1077     This parameter specifies the number of bytes to read from the target I2C\r
1078     slave device. This size must not exceed the size of the buffer pointed to by\r
1079     the read_buffer parameter.\r
1080  \r
1081   @param options:\r
1082     The options parameter is used to indicate if the I2C bus should be released\r
1083     on completion of the write-read transaction. Using the I2C_RELEASE_BUS\r
1084     constant for the options parameter causes a STOP bit to be generated at the\r
1085     end of the write-read transaction causing the bus to be released for other\r
1086     I2C devices to use. Using the I2C_HOLD_BUS constant as options parameter\r
1087     prevents a STOP bit from being generated at the end of the write-read\r
1088     transaction, preventing other I2C devices from initiating a bus transaction.\r
1089         \r
1090   @return none.  \r
1091   \r
1092   Example:\r
1093   @code\r
1094     #define COREI2C_BASE_ADDR    0xC0000000u\r
1095     #define COREI2C_DUMMY_ADDR   0x10u\r
1096     #define TX_LENGTH            16u\r
1097     #define RX_LENGTH            8u\r
1098 \r
1099     i2c_instance_t g_i2c_inst;\r
1100     uint8_t  rx_buffer[RX_LENGTH];\r
1101     uint8_t  read_length = RX_LENGTH;     \r
1102     uint8_t  tx_buffer[TX_LENGTH];\r
1103     uint8_t  write_length = TX_LENGTH;  \r
1104     \r
1105     void main( void )\r
1106     {\r
1107         uint8_t  target_slave_addr = 0x12;\r
1108         i2c_status_t status;\r
1109         // Initialize base CoreI2C instance\r
1110         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, COREI2C_DUMMY_ADDR,\r
1111                   I2C_PCLK_DIV_256 );\r
1112                   \r
1113         I2C_write_read( &g_i2c_inst, target_slave_addr, tx_buffer, write_length,\r
1114                         rx_buffer, read_length, I2C_RELEASE_BUS );\r
1115                         \r
1116         status = I2C_wait_complete( &g_i2c_inst, I2C_NO_TIMEOUT );\r
1117     }\r
1118   @endcode\r
1119  */\r
1120 void I2C_write_read\r
1121 (\r
1122     i2c_instance_t * this_i2c,\r
1123     uint8_t serial_addr,\r
1124     const uint8_t * addr_offset,\r
1125     uint16_t offset_size,\r
1126     uint8_t * read_buffer,\r
1127     uint16_t read_size,\r
1128     uint8_t options\r
1129 );\r
1130     \r
1131 /*-------------------------------------------------------------------------*//**\r
1132   I2C status\r
1133   ------------------------------------------------------------------------------\r
1134   This function indicates the current state of a CoreI2C channel.\r
1135   ------------------------------------------------------------------------------\r
1136   @param this_i2c:\r
1137     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1138     holding all data related to a specific CoreI2C channel. For example, if only\r
1139     one channel is initialized, this data structure holds the information of \r
1140     channel 0 of the instantiated CoreI2C hardware.\r
1141   ------------------------------------------------------------------------------\r
1142   @return\r
1143     The return value indicates the current state of a CoreI2C channel or the\r
1144     outcome of the previous transaction if no transaction is in progress. \r
1145     Possible return values are:\r
1146       I2C_SUCCESS\r
1147         The last I2C transaction has completed successfully.  \r
1148       I2C_IN_PROGRESS\r
1149         There is an I2C transaction in progress.\r
1150       I2C_FAILED\r
1151         The last I2C transaction failed.\r
1152       I2C_TIMED_OUT\r
1153         The request has failed to complete in the allotted time.      \r
1154   \r
1155   Example:\r
1156   @code\r
1157     i2c_instance_t g_i2c_inst;\r
1158     \r
1159     while( I2C_IN_PROGRESS == I2C_get_status( &g_i2c_inst ) )\r
1160     {\r
1161         // Do something useful while waiting for I2C operation to complete\r
1162         our_i2c_busy_task();\r
1163     }\r
1164     \r
1165     if( I2C_SUCCESS != I2C_get_status( &g_i2c_inst ) )\r
1166     {\r
1167         // Something went wrong... \r
1168         our_i2c_error_recovery( &g_i2c_inst );\r
1169     }\r
1170   @endcode\r
1171  */\r
1172 i2c_status_t I2C_get_status\r
1173 (\r
1174     i2c_instance_t * this_i2c\r
1175 );\r
1176 \r
1177 /*-------------------------------------------------------------------------*//**\r
1178   Wait for I2C transaction completion.\r
1179   ------------------------------------------------------------------------------\r
1180   This function waits for the current I2C transaction to complete. The return\r
1181   value indicates whether the last I2C transaction was successful or not.\r
1182   ------------------------------------------------------------------------------\r
1183   @param this_i2c:\r
1184     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1185     holding all data related to a specific CoreI2C channel. For example, if only\r
1186     one channel is initialized, this data structure holds the information of\r
1187     channel 0 of the instantiated CoreI2C hardware.\r
1188   @param timeout_ms:\r
1189     The timeout_ms parameter specified the delay within which the current I2C \r
1190     transaction is expected to complete. The time out delay is given in \r
1191     milliseconds. I2C_wait_complete() will return I2C_TIMED_OUT if the current\r
1192     transaction has not completed after the time out delay has expired. This\r
1193     parameter can be set to I2C_NO_TIMEOUT to indicate that I2C_wait_complete()\r
1194     must not time out.\r
1195   ------------------------------------------------------------------------------\r
1196   @return\r
1197     The return value indicates the outcome of the last I2C transaction. It can\r
1198     be one of the following: \r
1199       I2C_SUCCESS\r
1200         The last I2C transaction has completed successfully.\r
1201       I2C_FAILED\r
1202         The last I2C transaction failed.\r
1203       I2C_TIMED_OUT\r
1204         The last transaction failed to complete within the time out delay given\r
1205         as second parameter.\r
1206 \r
1207   Example:\r
1208   @code\r
1209     #define COREI2C_BASE_ADDR  0xC0000000u\r
1210     #define COREI2C_DUMMY_ADDR   0x10u\r
1211     #define DATA_LENGTH           16u\r
1212 \r
1213     i2c_instance_t g_i2c_inst;\r
1214 \r
1215     uint8_t  rx_buffer[DATA_LENGTH];\r
1216     uint8_t  read_length = DATA_LENGTH;     \r
1217 \r
1218     void main( void )\r
1219     {\r
1220         uint8_t  target_slave_addr = 0x12;\r
1221         i2c_status_t status;\r
1222         \r
1223         // Initialize base CoreI2C instance\r
1224         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, COREI2C_DUMMY_ADDR,\r
1225                   I2C_PCLK_DIV_256 );\r
1226         \r
1227         // Read data from Channel 0 of CoreI2C instance.\r
1228         I2C_read( &g_i2c_inst, target_slave_addr, rx_buffer, read_length,\r
1229                   I2C_RELEASE_BUS );\r
1230         \r
1231         // Wait for completion and record the outcome\r
1232         status = I2C_wait_complete( &g_i2c_inst, I2C_NO_TIMEOUT );\r
1233     }\r
1234   @endcode\r
1235  */\r
1236 i2c_status_t I2C_wait_complete\r
1237 (\r
1238     i2c_instance_t * this_i2c,\r
1239     uint32_t timeout_ms\r
1240 );\r
1241 \r
1242 /*-------------------------------------------------------------------------*//**\r
1243   Time out delay expiration.\r
1244   ------------------------------------------------------------------------------\r
1245   This function is used to control the expiration of the time out delay\r
1246   specified as a parameter to the I2C_wait_complete() function. It must be\r
1247   called from the interrupt service routine of a periodic interrupt source such\r
1248   as the Cortex-M3 SysTick timer interrupt. It takes the period of the interrupt\r
1249   source as its ms_since_last_tick parameter and uses it as the time base for\r
1250   the I2C_wait_complete() function\92s time out delay.\r
1251   \r
1252   Note: This function does not need to be called if the I2C_wait_complete()\r
1253         function is called with a timeout_ms value of I2C_NO_TIMEOUT.\r
1254   Note: If this function is not called then the I2C_wait_complete() function\r
1255         will behave as if its timeout_ms was specified as I2C_NO_TIMEOUT and it\r
1256         will not time out.\r
1257   Note: If this function is being called from an interrupt handler (e.g SysTick)\r
1258         it is important that the calling interrupt have a lower priority than\r
1259         the CoreI2C interrupt(s) to ensure any updates to shared data are\r
1260         protected.\r
1261   \r
1262   ------------------------------------------------------------------------------\r
1263   @param this_i2c:\r
1264     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1265     holding all data related to a specific CoreI2C channel. For example, if only\r
1266     one channel is initialized, this data structure holds the information of \r
1267     channel 0 of the instantiated CoreI2C hardware.\r
1268   @param ms_since_last_tick:\r
1269     The ms_since_last_tick parameter specifies the number of milliseconds that\r
1270     elapsed since the last call to I2C_system_tick(). This parameter would\r
1271     typically be a constant specifying the interrupt rate of a timer used to\r
1272     generate system ticks.\r
1273   ------------------------------------------------------------------------------\r
1274   @return\r
1275     none.\r
1276 \r
1277   Example:\r
1278     The example below shows an example of how the I2C_system_tick() function\r
1279     would be called in a Cortex-M3 based system. I2C_system_tick() is called for\r
1280     each I2C channel from the Cortex-M3 SysTick timer interrupt service routine.\r
1281     The SysTick is configured to generate an interrupt every 10 milliseconds in\r
1282     the example below.\r
1283   @code\r
1284     #define SYSTICK_INTERVAL_MS 10\r
1285    \r
1286     void SysTick_Handler(void)\r
1287     {\r
1288         I2C_system_tick(&g_core_i2c0, SYSTICK_INTERVAL_MS);\r
1289         I2C_system_tick(&g_core_i2c2, SYSTICK_INTERVAL_MS);\r
1290     }\r
1291   @endcode\r
1292  */\r
1293 void I2C_system_tick\r
1294 (\r
1295     i2c_instance_t * this_i2c,\r
1296     uint32_t ms_since_last_tick\r
1297 );\r
1298 \r
1299 /*******************************************************************************\r
1300  *******************************************************************************\r
1301  * \r
1302  *                           Slave specific functions\r
1303  * \r
1304  * The following functions are only used within the implementation of an I2C\r
1305  * slave device.\r
1306  */\r
1307 \r
1308 /*-------------------------------------------------------------------------*//**\r
1309   I2C slave transmit buffer configuration.\r
1310   ------------------------------------------------------------------------------\r
1311   This function specifies the memory buffer holding the data that will be sent\r
1312   to the I2C master when this CoreI2C channel is the target of an I2C read or\r
1313   write-read transaction.\r
1314   ------------------------------------------------------------------------------\r
1315   @param this_i2c:\r
1316     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1317     holding all data related to a specific CoreI2C channel. For example, if only\r
1318     one channel is initialized, this data structure holds the information of \r
1319     channel 0 of the instantiated CoreI2C hardware.\r
1320   \r
1321   @param tx_buffer:\r
1322     This parameter is a pointer to the memory buffer holding the data to be\r
1323     returned to the I2C master when this CoreI2C channel is the target of an\r
1324     I2C read or write-read transaction.\r
1325   \r
1326   @param tx_size:\r
1327     Size of the transmit buffer pointed to by the tx_buffer parameter.\r
1328 \r
1329   @return none.  \r
1330       \r
1331   Example:\r
1332   @code\r
1333     #define COREI2C_BASE_ADDR    0xC0000000u\r
1334     #define SLAVE_SER_ADDR       0x10u\r
1335     #define SLAVE_TX_BUFFER_SIZE 10u\r
1336 \r
1337     i2c_instance_t g_i2c_inst;\r
1338 \r
1339     uint8_t g_slave_tx_buffer[SLAVE_TX_BUFFER_SIZE] = { 1, 2, 3, 4, 5,\r
1340                                                         6, 7, 8, 9, 10 };\r
1341 \r
1342     void main( void )\r
1343     {\r
1344         // Initialize the CoreI2C driver with its base address, I2C serial\r
1345         // address and serial clock divider.\r
1346         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR,\r
1347                   I2C_PCLK_DIV_256 );\r
1348        \r
1349         // Specify the transmit buffer containing the data that will be\r
1350         // returned to the master during read and write-read transactions.\r
1351         I2C_set_slave_tx_buffer( &g_i2c_inst, g_slave_tx_buffer, \r
1352                                  sizeof(g_slave_tx_buffer) );\r
1353     }\r
1354   @endcode\r
1355  */\r
1356 void I2C_set_slave_tx_buffer\r
1357 (\r
1358     i2c_instance_t * this_i2c,\r
1359     const uint8_t * tx_buffer,\r
1360     uint16_t tx_size\r
1361 );\r
1362 \r
1363 /*-------------------------------------------------------------------------*//**\r
1364   I2C slave receive buffer configuration.\r
1365   ------------------------------------------------------------------------------\r
1366   This function specifies the memory buffer that will be used by the CoreI2C\r
1367   channel to receive data when it is a slave. This buffer is the memory where\r
1368   data will be stored when the CoreI2C channel is the target of an I2C master\r
1369   write transaction (i.e. when it is the slave).\r
1370   ------------------------------------------------------------------------------\r
1371   @param this_i2c:\r
1372     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1373     holding all data related to a specific CoreI2C channel. For example, if only\r
1374     one channel is initialized, this data structure holds the information of \r
1375     channel 0 of the instantiated CoreI2C hardware.\r
1376   \r
1377   @param rx_buffer:\r
1378     This parameter is a pointer to the memory buffer allocated by the caller\r
1379     software to be used as a slave receive buffer.\r
1380   \r
1381   @param rx_size:\r
1382     Size of the slave receive buffer. This is the amount of memory that is\r
1383     allocated to the buffer pointed to by rx_buffer.\r
1384     Note:   This buffer size indirectly specifies the maximum I2C write\r
1385             transaction length this CoreI2C channel can be the target of. This\r
1386             is because this CoreI2C channel responds to further received\r
1387             bytes with a non-acknowledge bit (NACK) as soon as its receive\r
1388             buffer is full. This causes the write transaction to fail.\r
1389             \r
1390   @return none.  \r
1391       \r
1392   Example:\r
1393   @code\r
1394     #define COREI2C_BASE_ADDR    0xC0000000u\r
1395     #define SLAVE_SER_ADDR       0x10u\r
1396     #define SLAVE_RX_BUFFER_SIZE 10u\r
1397 \r
1398     i2c_instance_t g_i2c_inst;\r
1399 \r
1400     uint8_t g_slave_rx_buffer[SLAVE_RX_BUFFER_SIZE];\r
1401 \r
1402     void main( void )\r
1403     {\r
1404         // Initialize the CoreI2C driver with its base address, I2C serial\r
1405         // address and serial clock divider.\r
1406         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR,\r
1407                   I2C_PCLK_DIV_256 );\r
1408        \r
1409         // Specify the buffer used to store the data written by the I2C master.\r
1410         I2C_set_slave_rx_buffer( &g_i2c_inst, g_slave_rx_buffer, \r
1411                                  sizeof(g_slave_rx_buffer) );\r
1412     }\r
1413   @endcode\r
1414  */\r
1415 void I2C_set_slave_rx_buffer\r
1416 (\r
1417     i2c_instance_t * this_i2c,\r
1418     uint8_t * rx_buffer,\r
1419     uint16_t rx_size\r
1420 );\r
1421 \r
1422 /*-------------------------------------------------------------------------*//**\r
1423   I2C slave memory offset length configuration.\r
1424   ------------------------------------------------------------------------------\r
1425   This function is used as part of the configuration of a CoreI2C channel for\r
1426   operation as a slave supporting write-read transactions. It specifies the\r
1427   number of bytes expected as part of the write phase of a write-read\r
1428   transaction. The bytes received during the write phase of a write-read\r
1429   transaction will be interpreted as an offset into the slave's transmit buffer.\r
1430   This allows random access into the I2C slave transmit buffer from a remote\r
1431   I2C master.\r
1432   ------------------------------------------------------------------------------\r
1433   @param this_i2c:\r
1434     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1435     holding all data related to a specific CoreI2C channel. For example, if only\r
1436     one channel is initialized, this data structure holds the information of \r
1437     channel 0 of the instantiated CoreI2C hardware.\r
1438   \r
1439   @param offset_length:\r
1440     The offset_length parameter configures the number of bytes to be interpreted\r
1441     by the CoreI2C slave as a memory offset value during the write phase of\r
1442     write-read transactions. The maximum value for the offset_length parameter\r
1443     is two. The value of offset_length has the following effect on the \r
1444     interpretation of the received data.\r
1445     \r
1446       If offset_length is 0, the offset into the transmit buffer is fixed at 0.\r
1447       \r
1448       If offset_length is 1, a single byte of received data is interpreted as an\r
1449       unsigned 8 bit offset value in the range 0 to 255.\r
1450       \r
1451       If offset_length is 2, 2 bytes of received data are interpreted as an\r
1452       unsigned 16 bit offset value in the range 0 to 65535. The first byte\r
1453       received in this case provides the high order bits of the offset and\r
1454       the second byte provides the low order bits.\r
1455       \r
1456     If the number of bytes received does not match the non 0 value of\r
1457     offset_length the transmit buffer offset is set to 0.\r
1458             \r
1459   @return none.  \r
1460       \r
1461   Example:\r
1462   @code\r
1463     #define COREI2C_BASE_ADDR    0xC0000000u\r
1464     #define SLAVE_SER_ADDR       0x10u\r
1465     #define SLAVE_TX_BUFFER_SIZE 10u\r
1466 \r
1467     i2c_instance_t g_i2c_inst;\r
1468 \r
1469     uint8_t g_slave_tx_buffer[SLAVE_TX_BUFFER_SIZE] = { 1, 2, 3, 4, 5,\r
1470                                                         6, 7, 8, 9, 10 };\r
1471 \r
1472     void main( void )\r
1473     {\r
1474         // Initialize the CoreI2C driver with its base address, I2C serial\r
1475         // address and serial clock divider.\r
1476         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR,\r
1477                   I2C_PCLK_DIV_256 );\r
1478         I2C_set_slave_tx_buffer( &g_i2c_inst, g_slave_tx_buffer, \r
1479                                  sizeof(g_slave_tx_buffer) );\r
1480         I2C_set_slave_mem_offset_length( &g_i2c_inst, 1 );\r
1481     }\r
1482   @endcode        \r
1483  */\r
1484 void I2C_set_slave_mem_offset_length\r
1485 (\r
1486     i2c_instance_t * this_i2c,\r
1487     uint8_t offset_length\r
1488 );\r
1489 \r
1490 /*-------------------------------------------------------------------------*//**\r
1491   I2C write handler registration. \r
1492   ------------------------------------------------------------------------------\r
1493   Register the function that is called to process the data written to this\r
1494   CoreI2C channel when it is the slave in an I2C write transaction.\r
1495   Note: If a write handler is registered, it is called on completion of the\r
1496         write phase of a write-read transaction and responsible for processing\r
1497         the received data in the slave receive buffer and populating the slave\r
1498         transmit buffer with the data that will be transmitted to the I2C master\r
1499         as part of the read phase of the write-read transaction. If a write\r
1500         handler is not registered, the write data of a write read transaction is\r
1501         interpreted as an offset into the slave\92s transmit buffer and handled by\r
1502         the driver.\r
1503   ------------------------------------------------------------------------------\r
1504   @param this_i2c:\r
1505     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1506     holding all data related to a specific CoreI2C channel. For example, if only\r
1507     one channel is initialized, this data structure holds the information of \r
1508     channel 0 of the instantiated CoreI2C hardware.\r
1509   \r
1510   @param handler:\r
1511     Pointer to the function that will process the I2C write request.\r
1512             \r
1513   @return none.  \r
1514       \r
1515   Example:\r
1516   @code\r
1517     #define COREI2C_BASE_ADDR    0xC0000000u\r
1518     #define SLAVE_SER_ADDR       0x10u\r
1519     #define SLAVE_TX_BUFFER_SIZE 10u\r
1520 \r
1521     i2c_instance_t g_i2c_inst;\r
1522 \r
1523     uint8_t g_slave_tx_buffer[SLAVE_TX_BUFFER_SIZE] = { 1, 2, 3, 4, 5,\r
1524                                                        6, 7, 8, 9, 10 };\r
1525 \r
1526     // local function prototype\r
1527     void slave_write_handler\r
1528     (\r
1529         i2c_instance_t * this_i2c,\r
1530         uint8_t * p_rx_data,\r
1531         uint16_t rx_size\r
1532     );\r
1533 \r
1534     void main( void )\r
1535     {\r
1536         // Initialize the CoreI2C driver with its base address, I2C serial\r
1537         // address and serial clock divider.\r
1538         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR, \r
1539                   I2C_PCLK_DIV_256 );\r
1540         I2C_set_slave_tx_buffer( &g_i2c_inst, g_slave_tx_buffer, \r
1541                                  sizeof(g_slave_tx_buffer) );\r
1542         I2C_set_slave_mem_offset_length( &g_i2c_inst, 1 );\r
1543         I2C_register_write_handler( &g_i2c_inst, slave_write_handler );\r
1544     }\r
1545   @endcode    \r
1546 */\r
1547 void I2C_register_write_handler\r
1548 (\r
1549     i2c_instance_t * this_i2c,\r
1550     i2c_slave_wr_handler_t handler\r
1551 );\r
1552 \r
1553 /*-------------------------------------------------------------------------*//**\r
1554   I2C slave enable.\r
1555   ------------------------------------------------------------------------------\r
1556   This function enables slave mode operation for a CoreI2C channel. It enables \r
1557   the CoreI2C slave to receive data when it is the target of an I2C read, write\r
1558   or write-read transaction.\r
1559   ------------------------------------------------------------------------------\r
1560   @param this_i2c:\r
1561     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1562     holding all data related to a specific CoreI2C channel. For example, if only\r
1563     one channel is initialized, this data structure holds the information of \r
1564     channel 0 of the instantiated CoreI2C hardware.\r
1565 \r
1566   @return none.\r
1567 \r
1568   Example:\r
1569   @code\r
1570     // Enable I2C slave\r
1571     I2C_enable_slave( &g_i2c_inst );\r
1572   @endcode\r
1573  */\r
1574 void I2C_enable_slave\r
1575 (\r
1576     i2c_instance_t * this_i2c\r
1577 );\r
1578 \r
1579 /*-------------------------------------------------------------------------*//**\r
1580   I2C slave disable.\r
1581   ------------------------------------------------------------------------------\r
1582   This function disables slave mode operation for a CoreI2C channel. It stops\r
1583   the CoreI2C slave acknowledging I2C read, write or write-read transactions\r
1584   targeted at it.\r
1585   ------------------------------------------------------------------------------\r
1586   @param this_i2c:\r
1587     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1588     holding all data related to a specific CoreI2C channel. For example, if only\r
1589     one channel is initialized, this data structure holds the information of \r
1590     channel 0 of the instantiated CoreI2C hardware.\r
1591 \r
1592   @return none.\r
1593 \r
1594   Example:\r
1595   @code\r
1596    // Disable I2C slave\r
1597    I2C_disable_slave( &g_i2c_inst );\r
1598   @endcode\r
1599  */\r
1600 void I2C_disable_slave\r
1601 (\r
1602     i2c_instance_t * this_i2c\r
1603 );\r
1604 /*-------------------------------------------------------------------------*//**\r
1605   Set I2C slave second address.\r
1606   ------------------------------------------------------------------------------\r
1607   The function I2C_set_slave_second_addr() sets the secondary slave address for\r
1608   a CoreI2C slave device. This is an additional slave address which might be\r
1609   required in certain applications, for example to enable fail-safe operation in\r
1610   a system. As the CoreI2C device supports 7-bit addressing, the highest value\r
1611   which can be assigned to second slave address is 127 (0x7F).\r
1612   Note: This function does not support CoreI2C hardware configured with a fixed \r
1613       second slave address.  The current implementation of the ADDR1[0] register\r
1614       bit makes it difficult for the driver to support both programmable and\r
1615       fixed second slave address, so we choose to support programmable only.\r
1616   ------------------------------------------------------------------------------\r
1617   @param this_i2c:\r
1618     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1619     holding all data related to a specific CoreI2C channel. For example, if only\r
1620     one channel is initialized, this data structure holds the information of \r
1621     channel 0 of the instantiated CoreI2C hardware.\r
1622 \r
1623   @param second_slave_addr:\r
1624     The second_slave_addr parameter is the secondary slave address of the I2C\r
1625     device.\r
1626 \r
1627   @return\r
1628     none.\r
1629 \r
1630   Example:\r
1631   @code\r
1632     #define COREI2C_BASE_ADDR  0xC0000000u\r
1633     #define SLAVE_SER_ADDR     0x10u\r
1634     #define SECOND_SLAVE_ADDR  0x20u\r
1635 \r
1636     i2c_instance_t g_i2c_inst;\r
1637     void main( void )\r
1638     {\r
1639         // Initialize the CoreI2C driver with its base address, primary I2C\r
1640         // serial address and serial clock divider.\r
1641         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR, \r
1642                   I2C_PCLK_DIV_256 );\r
1643         I2C_set_slave_second_addr( &g_i2c_inst, SECOND_SLAVE_ADDR );\r
1644     }\r
1645   @endcode\r
1646  */\r
1647 void I2C_set_slave_second_addr\r
1648 (\r
1649     i2c_instance_t * this_i2c,\r
1650     uint8_t second_slave_addr\r
1651 );\r
1652 \r
1653 /*-------------------------------------------------------------------------*//**\r
1654   Disable second slave address.\r
1655   ------------------------------------------------------------------------------\r
1656   The function I2C_disable_slave_second_addr() disables the secondary slave\r
1657   address of the CoreI2C slave device. \r
1658   Note: This version of the driver only supports CoreI2C hardware configured\r
1659         with a programmable second slave address.\r
1660   ------------------------------------------------------------------------------\r
1661   @param this_i2c:\r
1662     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1663     holding all data related to a specific CoreI2C channel. For example, if only\r
1664     one channel is initialized, this data structure holds the information of \r
1665     channel 0 of the instantiated CoreI2C hardware.\r
1666 \r
1667   @return\r
1668     none.\r
1669 \r
1670   Example:\r
1671   @code\r
1672     i2c_instance_t g_i2c_inst;\r
1673     I2C_disable_slave_second_addr( &g_i2c_inst);\r
1674   @endcode\r
1675  */\r
1676 void I2C_disable_slave_second_addr\r
1677 (\r
1678     i2c_instance_t * this_i2c\r
1679 );\r
1680 \r
1681 /*-------------------------------------------------------------------------*//**\r
1682   The I2C_set_gca() function is used to set the general call acknowledgement bit\r
1683   of a CoreI2C slave device. This allows all channels of the CoreI2C slave\r
1684   device respond to a general call or broadcast message from an I2C master.\r
1685   ------------------------------------------------------------------------------\r
1686   @param this_i2c:\r
1687     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1688     holding all data related to a specific CoreI2C channel. For example, if only\r
1689     one channel is initialized, this data structure holds the information of \r
1690     channel 0 of the instantiated CoreI2C hardware.\r
1691 \r
1692   @return\r
1693     none.\r
1694 \r
1695   Example:\r
1696   @code\r
1697     i2c_instance_t g_i2c_inst;\r
1698 \r
1699     // Enable recognition of the General Call Address\r
1700     I2C_set_gca( &g_i2c_inst ); \r
1701   @endcode\r
1702  */\r
1703 void I2C_set_gca\r
1704 (\r
1705     i2c_instance_t * this_i2c\r
1706 );\r
1707 \r
1708 /*-------------------------------------------------------------------------*//**\r
1709   The I2C_clear_gca() function is used to clear the general call acknowledgement\r
1710   bit of a CoreI2C slave device. This will stop all channels of the I2C slave\r
1711   device responding to any general call or broadcast message from the master.\r
1712   ------------------------------------------------------------------------------\r
1713   @param this_i2c:\r
1714     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1715     holding all data related to a specific CoreI2C channel. For example, if only\r
1716     one channel is initialized, this data structure holds the information of \r
1717     channel 0 of the instantiated CoreI2C hardware.\r
1718 \r
1719   @return\r
1720     none.\r
1721 \r
1722   Example:\r
1723   @code\r
1724     i2c_instance_t g_i2c_inst;\r
1725 \r
1726     // Disable recognition of the General Call Address\r
1727     I2C_clear_gca( &g_i2c_inst );\r
1728   @endcode\r
1729  */\r
1730 \r
1731 void I2C_clear_gca\r
1732 (\r
1733     i2c_instance_t * this_i2c\r
1734 );\r
1735 \r
1736 /*------------------------------------------------------------------------------\r
1737                       I2C SMBUS specific APIs\r
1738  ----------------------------------------------------------------------------*/\r
1739 \r
1740 /*-------------------------------------------------------------------------*//**\r
1741   The I2C_smbus_init() function enables SMBus timeouts and status logic for a\r
1742   CoreI2C channel.\r
1743   Note: This and any of the other SMBus related functionality will only have an\r
1744         effect if the CoreI2C was instantiated with the Generate SMBus Logic\r
1745         option checked.\r
1746   Note: If the CoreI2C was instantiated with the Generate IPMI Logic option\r
1747         checked this function will enable the IPMI 3mS SCL low timeout but none\r
1748         of the other SMBus functions will have any effect.\r
1749   ------------------------------------------------------------------------------\r
1750   @param this_i2c:\r
1751     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1752     holding all data related to a specific CoreI2C channel. For example, if only\r
1753     one channel is initialized, this data structure holds the information of \r
1754     channel 0 of the instantiated CoreI2C hardware.\r
1755 \r
1756   @return\r
1757     none.\r
1758 \r
1759   Example:\r
1760   @code\r
1761    #define COREI2C_BASE_ADDR  0xC0000000u\r
1762    #define SLAVE_SER_ADDR     0x10u\r
1763 \r
1764    i2c_instance_t g_i2c_inst;\r
1765 \r
1766    void system_init( void )\r
1767    {\r
1768         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR,\r
1769                   I2C_PCLK_DIV_256 );\r
1770         \r
1771         // Initialize SMBus feature\r
1772         I2C_smbus_init( &g_i2c_inst);\r
1773    }\r
1774   @endcode    \r
1775  */\r
1776 void I2C_smbus_init\r
1777 (\r
1778     i2c_instance_t * this_i2c\r
1779 );\r
1780 \r
1781 /*-------------------------------------------------------------------------*//**\r
1782   The I2C_enable_smbus_irq() function is used to enable the CoreI2C channel\92s \r
1783   SMBSUS and SMBALERT SMBus interrupts.\r
1784   ------------------------------------------------------------------------------\r
1785   @param this_i2c:\r
1786     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1787     holding all data related to a specific CoreI2C channel. For example, if only\r
1788     one channel is initialized, this data structure holds the information of \r
1789     channel 0 of the instantiated CoreI2C hardware.\r
1790 \r
1791   @param irq_type\r
1792     The irq_type specify the SMBUS interrupt(s) which will be enabled.\r
1793     The two possible interrupts are:\r
1794       I2C_SMBALERT_IRQ\r
1795       I2C_SMBSUS_IRQ\r
1796     To enable both ints in one call, use I2C_SMBALERT_IRQ | I2C_SMBSUS_IRQ.\r
1797     \r
1798   @return\r
1799     none\r
1800   \r
1801   Example:\r
1802   @code\r
1803     #define COREI2C_BASE_ADDR  0xC0000000u\r
1804     #define SLAVE_SER_ADDR     0x10u\r
1805 \r
1806     i2c_instance_t g_i2c_inst;\r
1807 \r
1808     void main( void )\r
1809     {\r
1810         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR,\r
1811                   I2C_PCLK_DIV_256 );\r
1812         \r
1813         // Initialize SMBus feature\r
1814         I2C_smbus_init( &g_i2c_inst );\r
1815         \r
1816         // Enable both I2C_SMBALERT_IRQ & I2C_SMBSUS_IRQ interrupts\r
1817         I2C_enable_smbus_irq( &g_i2c_inst,\r
1818                               (uint8_t)(I2C_SMBALERT_IRQ | I2C_SMBSUS_IRQ) );\r
1819    }\r
1820    @endcode\r
1821  */\r
1822 void I2C_enable_smbus_irq\r
1823 (\r
1824     i2c_instance_t * this_i2c,\r
1825     uint8_t  irq_type\r
1826 );\r
1827 \r
1828 /*-------------------------------------------------------------------------*//**\r
1829   The I2C_disable_smbus_irq() function is used to disable the CoreI2C channel\92s\r
1830   SMBSUS and SMBALERT SMBus interrupts.\r
1831   ------------------------------------------------------------------------------\r
1832   @param this_i2c:\r
1833     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1834     holding all data related to a specific CoreI2C channel. For example, if only\r
1835     one channel is initialized, this data structure holds the information of \r
1836     channel 0 of the instantiated CoreI2C hardware.\r
1837 \r
1838   @param irq_type\r
1839     The irq_type specifies the SMBUS interrupt(s) which will be disabled.\r
1840     The two possible interrupts are:\r
1841       I2C_SMBALERT_IRQ\r
1842       I2C_SMBSUS_IRQ\r
1843     To disable both ints in one call, use I2C_SMBALERT_IRQ | I2C_SMBSUS_IRQ.\r
1844 \r
1845   @return\r
1846     none.\r
1847       \r
1848   Example:\r
1849   @code\r
1850     #define COREI2C_BASE_ADDR  0xC0000000u\r
1851     #define SLAVE_SER_ADDR     0x10u\r
1852 \r
1853     i2c_instance_t g_i2c_inst;\r
1854 \r
1855     void main( void )\r
1856     {\r
1857         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR,\r
1858                   I2C_PCLK_DIV_256 );\r
1859         \r
1860         // Initialize SMBus feature\r
1861         I2C_smbus_init( &g_i2c_inst );\r
1862         \r
1863         // Enable both SMBALERT & SMBSUS interrupts\r
1864         I2C_enable_smbus_irq( &g_i2c_inst,\r
1865                               (uint8_t)(I2C_SMBALERT_IRQ | I2C_SMBSUS_IRQ));\r
1866         \r
1867         ...        \r
1868 \r
1869         // Disable the SMBALERT interrupt\r
1870         I2C_disable_smbus_irq( &g_i2c_inst, I2C_SMBALERT_IRQ );\r
1871     }\r
1872   @endcode\r
1873  */\r
1874 void I2C_disable_smbus_irq\r
1875 (\r
1876     i2c_instance_t * this_i2c,\r
1877     uint8_t  irq_type\r
1878 );\r
1879 \r
1880 /*-------------------------------------------------------------------------*//**\r
1881   The function I2C_suspend_smbus_slave() forces any SMBUS slave devices\r
1882   connected to a CoreI2C channel into power down or suspend mode by asserting\r
1883   the channel's SMBSUS signal. The CoreI2C channel is the SMBus master in this\r
1884   case.\r
1885   ------------------------------------------------------------------------------\r
1886   @param this_i2c:\r
1887     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1888     holding all data related to a specific CoreI2C channel. For example, if only\r
1889     one channel is initialized, this data structure holds the information of \r
1890     channel 0 of the instantiated CoreI2C hardware.\r
1891 \r
1892   @return\r
1893     none.\r
1894     \r
1895   Example:\r
1896   @code\r
1897     #define COREI2C_BASE_ADDR  0xC0000000u\r
1898     #define SLAVE_SER_ADDR     0x10u\r
1899 \r
1900     i2c_instance_t g_i2c_inst;\r
1901     \r
1902     void main( void )\r
1903     {\r
1904         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR, \r
1905                   I2C_PCLK_DIV_256 );\r
1906 \r
1907         // Initialize SMBus feature\r
1908         I2C_smbus_init( &g_i2c_inst );\r
1909 \r
1910         // suspend SMBus slaves\r
1911         I2C_suspend_smbus_slave( &g_i2c_inst );\r
1912 \r
1913         ...\r
1914 \r
1915         // Re-enable SMBus slaves\r
1916         I2C_resume_smbus_slave( &g_i2c_inst );\r
1917     }\r
1918   @endcode\r
1919  */\r
1920 void I2C_suspend_smbus_slave\r
1921 (\r
1922     i2c_instance_t * this_i2c\r
1923 );\r
1924 \r
1925 /*-------------------------------------------------------------------------*//**\r
1926   The function I2C_resume_smbus_slave() de-asserts the CoreI2C channel's SMBSUS\r
1927   signal to take any connected slave devices out of suspend mode. The CoreI2C\r
1928   channel is the SMBus master in this case.\r
1929   ------------------------------------------------------------------------------\r
1930   @param this_i2c:\r
1931     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1932     holding all data related to a specific CoreI2C channel. For example, if only\r
1933     one channel is initialized, this data structure holds the information of \r
1934     channel 0 of the instantiated CoreI2C hardware.\r
1935 \r
1936   @return\r
1937     none.\r
1938     \r
1939   Example:\r
1940   @code\r
1941     #define COREI2C_BASE_ADDR  0xC0000000u\r
1942     #define SLAVE_SER_ADDR     0x10u\r
1943 \r
1944     i2c_instance_t g_i2c_inst;\r
1945     \r
1946     void main( void )\r
1947     {\r
1948         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR, \r
1949                   I2C_PCLK_DIV_256 );\r
1950 \r
1951         // Initialize SMBus feature\r
1952         I2C_smbus_init( &g_i2c_inst );\r
1953 \r
1954         // suspend SMBus slaves\r
1955         I2C_suspend_smbus_slave( &g_i2c_inst );\r
1956 \r
1957         ...\r
1958 \r
1959         // Re-enable SMBus slaves\r
1960         I2C_resume_smbus_slave( &g_i2c_inst );\r
1961     }\r
1962   @endcode\r
1963  */\r
1964 void I2C_resume_smbus_slave\r
1965 (\r
1966     i2c_instance_t * this_i2c\r
1967 );\r
1968 \r
1969 /*-------------------------------------------------------------------------*//**\r
1970   The I2C_reset_smbus() function resets the CoreI2C channel's SMBus connection\r
1971   by forcing SCLK low for 35mS. The reset is automatically cleared after 35ms\r
1972   have elapsed. The CoreI2C channel is the SMBus master in this case.\r
1973   ------------------------------------------------------------------------------\r
1974   @param this_i2c:\r
1975     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
1976     holding all data related to a specific CoreI2C channel. For example, if only\r
1977     one channel is initialized, this data structure holds the information of \r
1978     channel 0 of the instantiated CoreI2C hardware.\r
1979 \r
1980   @return\r
1981     none.\r
1982 \r
1983   Example:\r
1984   @code\r
1985     #define COREI2C_BASE_ADDR  0xC0000000u\r
1986     #define SLAVE_SER_ADDR     0x10u\r
1987 \r
1988     i2c_instance_t g_i2c_inst;\r
1989     \r
1990     void main( void )\r
1991     {\r
1992         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR, \r
1993                   I2C_PCLK_DIV_256 );\r
1994 \r
1995         // Initialize SMBus feature\r
1996         I2C_smbus_init( &g_i2c_inst );\r
1997 \r
1998         // Make sure the SMBus channel is in a known state by resetting it\r
1999         I2C_reset_smbus( &g_i2c_inst ); \r
2000     }\r
2001   @endcode\r
2002  */\r
2003 void I2C_reset_smbus\r
2004 (\r
2005     i2c_instance_t * this_i2c\r
2006 );\r
2007 \r
2008 /*-------------------------------------------------------------------------*//**\r
2009   The I2C_set_smbus_alert() function is used to force master communication with\r
2010   an I2C slave device by asserting the CoreI2C channel\92s SMBALERT signal. The\r
2011   CoreI2C channel is the SMBus slave in this case.\r
2012   ------------------------------------------------------------------------------\r
2013   @param this_i2c:\r
2014     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
2015     holding all data related to a specific CoreI2C channel. For example, if only\r
2016     one channel is initialized, this data structure holds the information of \r
2017     channel 0 of the instantiated CoreI2C hardware.\r
2018 \r
2019   @return\r
2020     none.\r
2021 \r
2022   Example:\r
2023   @code\r
2024     #define COREI2C_BASE_ADDR  0xC0000000u\r
2025     #define SLAVE_SER_ADDR     0x10u\r
2026 \r
2027     i2c_instance_t g_i2c_inst;\r
2028     \r
2029     void main( void )\r
2030     {\r
2031         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR, \r
2032                   I2C_PCLK_DIV_256 );\r
2033 \r
2034         // Initialize SMBus feature\r
2035         I2C_smbus_init( &g_i2c_inst );\r
2036 \r
2037         // Get the SMBus masters attention\r
2038         I2C_set_smbus_alert( &g_i2c_inst );\r
2039 \r
2040         ...\r
2041 \r
2042         // Once we are happy, drop the alert\r
2043         I2C_clear_smbus_alert( &g_i2c_inst );\r
2044     }\r
2045   @endcode\r
2046  */\r
2047 void I2C_set_smbus_alert\r
2048 (\r
2049     i2c_instance_t * this_i2c\r
2050 );\r
2051 \r
2052 /*-------------------------------------------------------------------------*//**\r
2053   The I2C_clear_smbus_alert() function is used de-assert the CoreI2C channel\92s \r
2054   SMBALERT signal once a slave device has had a response from the master. The\r
2055   CoreI2C channel is the SMBus slave in this case.\r
2056   ------------------------------------------------------------------------------\r
2057   @param this_i2c:\r
2058     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
2059     holding all data related to a specific CoreI2C channel. For example, if only\r
2060     one channel is initialized, this data structure holds the information of \r
2061     channel 0 of the instantiated CoreI2C hardware.\r
2062 \r
2063   @return\r
2064     none.\r
2065     \r
2066   Example:\r
2067   @code\r
2068     #define COREI2C_BASE_ADDR  0xC0000000u\r
2069     #define SLAVE_SER_ADDR     0x10u\r
2070 \r
2071     i2c_instance_t g_i2c_inst;\r
2072     \r
2073     void main( void )\r
2074     {\r
2075         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR, \r
2076                   I2C_PCLK_DIV_256 );\r
2077 \r
2078         // Initialize SMBus feature\r
2079         I2C_smbus_init( &g_i2c_inst );\r
2080 \r
2081         // Get the SMBus masters attention\r
2082         I2C_set_smbus_alert( &g_i2c_inst );\r
2083 \r
2084         ...\r
2085 \r
2086         // Once we are happy, drop the alert\r
2087         I2C_clear_smbus_alert( &g_i2c_inst );\r
2088     }\r
2089   @endcode\r
2090  */\r
2091 void I2C_clear_smbus_alert\r
2092 (\r
2093     i2c_instance_t * this_i2c\r
2094 );\r
2095 \r
2096 /*-------------------------------------------------------------------------*//**\r
2097   The I2C_get_irq_status function returns information on which interrupts are\r
2098   currently pending in a CoreI2C channel.\r
2099   The interrupts supported by CoreI2C are:\r
2100     * SMBUSALERT\r
2101     * SMBSUS\r
2102     * INTR\r
2103   The macros I2C_NO_IRQ, I2C_SMBALERT_IRQ, I2C_SMBSUS_IRQ and I2C_INTR_IRQ are\r
2104   provided for use with this function.\r
2105   ------------------------------------------------------------------------------\r
2106   @param this_i2c:\r
2107     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
2108     holding all data related to a specific CoreI2C channel. For example, if only\r
2109     one channel is initialized, this data structure holds the information of \r
2110     channel 0 of the instantiated CoreI2C hardware.\r
2111 \r
2112   @return\r
2113     This function returns the status of the CoreI2C channel\92s interrupts as a \r
2114     single byte bitmap where a bit is set to indicate a pending interrupt.\r
2115     The following are the bit positions associated with each interrupt type:\r
2116         Bit 0 - SMBUS_ALERT_IRQ\r
2117         Bit 1 - SMBSUS_IRQ\r
2118         Bit 2 - INTR_IRQ\r
2119     It returns 0, if there are no pending interrupts.\r
2120 \r
2121   Example\r
2122   @code\r
2123    #define COREI2C_BASE_ADDR  0xC0000000u\r
2124    #define SLAVE_SER_ADDR     0x10u\r
2125 \r
2126    i2c_instance_t g_i2c_inst;\r
2127    \r
2128    void main( void )\r
2129    {\r
2130         uint8_t irq_to_enable = I2C_SMBALERT_IRQ | I2C_SMBSUS_IRQ;\r
2131         uint8_t pending_irq = 0u;\r
2132         \r
2133         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR,\r
2134                   I2C_PCLK_DIV_256 );\r
2135 \r
2136         // Initialize SMBus feature\r
2137         I2C_smbus_init( &g_i2c_inst );\r
2138 \r
2139         // Enable both I2C_SMBALERT_IRQ & I2C_SMBSUS_IRQ irq\r
2140         I2C_enable_smbus_irq( &g_i2c_inst, irq_to_enable );\r
2141 \r
2142         // Get I2C IRQ type\r
2143         pending_irq = I2C_get_irq_status( &g_i2c_inst );\r
2144 \r
2145         // Let's assume, in system, INTR and SMBALERT IRQ is pending.\r
2146         // So pending_irq will return status of both the IRQs\r
2147 \r
2148         if( pending_irq & I2C_SMBALERT_IRQ )\r
2149         {\r
2150            // if true, it means SMBALERT_IRQ is there in pending IRQ list\r
2151         }\r
2152         if( pending_irq & I2C_INTR_IRQ )\r
2153         {\r
2154            // if true, it means I2C_INTR_IRQ is there in pending IRQ list\r
2155         }\r
2156    }\r
2157   @endcode\r
2158  */\r
2159 uint8_t I2C_get_irq_status\r
2160 (\r
2161     i2c_instance_t * this_i2c\r
2162 );\r
2163 \r
2164 /*-------------------------------------------------------------------------*//**\r
2165   The I2C_set_user_data() function is used to allow the association of a block\r
2166   of application specific data with a CoreI2C channel. The composition of the \r
2167   data block is an application matter and the driver simply provides the means\r
2168   for the application to set and retrieve the pointer. This may for example be\r
2169   used to provide additional channel specific information to the slave write \r
2170   handler.\r
2171   ------------------------------------------------------------------------------\r
2172   @param this_i2c:\r
2173     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
2174     holding all data related to a specific CoreI2C channel. For example, if only\r
2175     one channel is initialized, this data structure holds the information of \r
2176     channel 0 of the instantiated CoreI2C hardware.\r
2177 \r
2178   @param p_user_data:\r
2179     The p_user_data parameter is a pointer to the user specific data block for\r
2180     this channel. It is defined as void * as the driver does not know the actual\r
2181     type of data being pointed to and simply stores the pointer for later\r
2182     retrieval by the application.\r
2183 \r
2184   @return\r
2185     none.\r
2186     \r
2187   Example\r
2188   @code\r
2189     #define COREI2C_BASE_ADDR  0xC0000000u\r
2190     #define SLAVE_SER_ADDR     0x10u\r
2191 \r
2192     i2c_instance_t g_i2c_inst;\r
2193     app_data_t channel_xdata;\r
2194   \r
2195     void main( void )\r
2196     {\r
2197         app_data_t *p_xdata;\r
2198 \r
2199         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR, \r
2200                   I2C_PCLK_DIV_256 );\r
2201 \r
2202         // Store location of user data in instance structure\r
2203         I2C_set_user_data( &g_i2c_inst, (void *)&channel_xdata );\r
2204 \r
2205         ...\r
2206 \r
2207         // Retrieve location of user data and do some work on it\r
2208         p_xdata = (app_data_t *)I2C_get_user_data( &g_i2c_inst );\r
2209         if( NULL != p_xdata )\r
2210         {\r
2211             p_xdata->foo = 123;\r
2212         }\r
2213     }\r
2214   @endcode\r
2215  */\r
2216 void I2C_set_user_data\r
2217 (\r
2218     i2c_instance_t * this_i2c,\r
2219     void * p_user_data\r
2220 );\r
2221 \r
2222 /*-------------------------------------------------------------------------*//**\r
2223   The I2C_get_user_data() function is used to allow the retrieval of the address\r
2224   of a block of application specific data associated with a CoreI2C channel.\r
2225   The composition of the data block is an application matter and the driver \r
2226   simply provides the means for the application to set and retrieve the pointer.\r
2227   This may for example be used to provide additional channel specific\r
2228   information to the slave write handler.\r
2229   ------------------------------------------------------------------------------\r
2230   @param this_i2c:\r
2231     The this_i2c parameter is a pointer to the i2c_instance_t data structure\r
2232     holding all data related to a specific CoreI2C channel. For example, if only\r
2233     one channel is initialized, this data structure holds the information of \r
2234     channel 0 of the instantiated CoreI2C hardware.\r
2235 \r
2236   @return\r
2237     This function returns a pointer to the user specific data block for this \r
2238     channel. It is defined as void * as the driver does not know the actual type\r
2239     of data being pointed. If no user data has been registered for this channel\r
2240     a NULL pointer is returned.\r
2241     \r
2242   Example\r
2243   @code\r
2244     #define COREI2C_BASE_ADDR  0xC0000000u\r
2245     #define SLAVE_SER_ADDR     0x10u\r
2246 \r
2247     i2c_instance_t g_i2c_inst;\r
2248     app_data_t channel_xdata;\r
2249   \r
2250     void main( void )\r
2251     {\r
2252         app_data_t *p_xdata;\r
2253 \r
2254         I2C_init( &g_i2c_inst, COREI2C_BASE_ADDR, SLAVE_SER_ADDR,\r
2255                   I2C_PCLK_DIV_256 );\r
2256 \r
2257         // Store location of user data in instance structure\r
2258         I2C_set_user_data( &g_i2c_inst, (void *)&channel_xdata );\r
2259 \r
2260         ...\r
2261         \r
2262         // Retrieve location of user data and do some work on it\r
2263         p_xdata = (app_data_t *)I2C_get_user_data( &g_i2c_inst );\r
2264         if( NULL != p_xdata )\r
2265         {\r
2266             p_xdata->foo = 123;\r
2267         }\r
2268     }\r
2269   @endcode\r
2270  */\r
2271 void * I2C_get_user_data\r
2272 (\r
2273     i2c_instance_t * this_i2c\r
2274 );\r
2275 \r
2276 #ifdef __cplusplus\r
2277 }\r
2278 #endif\r
2279 \r
2280 #endif\r