begriffs open source - cmsis/blob - CMSIS/DoxyGen/Driver/src/Driver_I2C.c

   1 /**
   2 \defgroup i2c_interface_gr I2C Interface
   3 \brief    Driver API for I2C Bus Peripheral (%Driver_I2C.h)
   4 \details
   5
   6 I<sup>2</sup>C (Inter-Integrated Circuit, referred to as I-squared-C, I-two-C, or IIC) is a multi-master serial single-ended bus and is mostly used
   7 on single boards, but can also connect to components which are linked via cable.
   8
   9 Most significant features of the I<sup>2</sup>C bus include:
  10  - Only two bus lines are required
  11  - I<sup>2</sup>C is a true multi-master bus. Simple master/slave relationships exist between all components
  12  - A baud rate is not required; the master device determines a bus clock
  13  - Each connected device is addressable by a unique address
  14  - Providing arbitration and collision detection
  15
  16 For more information about I<sup>2</sup>C refer to the following web pages:
  17   - Wikipedia: <a href="http://en.wikipedia.org/wiki/I%C2%B2C" target="_blank">I<sup>2</sup>C</a>
  18   - <a href="http://www.i2c-bus.org" target="_blank">www.i2c-bus.org</a>.
  19
  20 Devices can operation in Master or Slave mode:
  21
  22  - To operate in Master mode call the functions \ref ARM_I2C_MasterTransmit or \ref ARM_I2C_MasterReceive. These functions get as argument a <em>slave address</em>.
  23
  24  - To operate in Slave mode set the <em>slave address</em> using the function \ref ARM_I2C_Control. The functions \ref ARM_I2C_SlaveTransmit or \ref ARM_I2C_SlaveReceive are used to transfer data in Slave mode.
  25
  26 <b>I<sup>2</sup>C Slave Address</b>
  27
  28 Depending on the device, I<sup>2</sup>C supports 7-bit and 10-bit Slaves addresses.
  29 The element <em>address_10_bit</em> in \ref ARM_I2C_CAPABILITIES indicates that the driver is able to handle 10-bit addresses.
  30 A 10-bit Slave address is ORed with \ref ARM_I2C_ADDRESS_10BIT.
  31
  32 I<sup>2</sup>C also supports a General Call to all Slaves by using the slave address value \token{0}.
  33 A General Call is recognized by Slaves have a slave address value \ref ARM_I2C_ADDRESS_GC registered with the
  34 function \ref ARM_I2C_Control.
  35
  36 <b>Block Diagram</b>
  37
  38 The I2C driver allows you to connect low-speed peripherals to a motherboard, embedded system, cellphone, or other electronic device.
  39
  40 \image html I2C_BlockDiagram.png  "Master/Slave connected via I2C interface"
  41
  42
  43 <b>I<sup>2</sup>C API</b>
  44
  45 The following header files define the Application Programming Interface (API) for the I<sup>2</sup>C interface:
  46   - \b %Driver_I2C.h : Driver API for I2C Bus Peripheral
  47
  48 The driver implementation is a typical part of the Device Family Pack (DFP) that supports the
  49 peripherals of the microcontroller family.
  50
  51
  52 <b>Driver Functions</b>
  53
  54 The driver functions are published in the access struct as explained in \ref DriverFunctions
  55   - \ref ARM_DRIVER_I2C : access struct for I2C driver functions
  56
  57
  58 \anchor i2c_example <b>Example Code</b>
  59
  60 The following example code shows the usage of the I<sup>2</sup>C interface in Master mode.
  61
  62 \include I2C_Demo.c
  63
  64 The following example code shows the usage of the I<sup>2</sup>C interface in Slave mode.
  65
  66 \include I2C_SlaveDemo.c
  67
  68 @{
  69 */
  70
  71
  72 /**
  73 \struct     ARM_DRIVER_I2C
  74 \details
  75 The functions of the I2C interface are accessed by function pointers exposed by this structure. Refer to \ref DriverFunctions for
  76 overview information.
  77
  78 Each instance of an I2C provides such an access structure. The instance is indicated by
  79 a postfix in the symbol name of the access structure, for example:
  80  - \b Driver_I2C0 is the name of the access struct of the first instance (no. 0).
  81  - \b Driver_I2C1 is the name of the access struct of the second instance (no. 1).
  82
  83
  84 A configuration setting in the middleware allows connecting the middleware to a specific driver instance <b>%Driver_I2C<i>n</i></b>.
  85 The default is \token{0}, which connects a middleware to the first instance of a driver.
  86 *******************************************************************************************************************/
  87
  88 /**
  89 \struct     ARM_I2C_CAPABILITIES
  90 \details
  91 An I2C driver can be implemented with different capabilities.
  92 The data fields of this struct encode the capabilities implemented by this driver.
  93
  94 The element \em address_10_bit indicates that the driver is able to handle 10-bit addressing natively.
  95 User can still emulate the 10-bit addressing in software if the driver does not support it.
  96
  97 <b>Returned by:</b>
  98   - \ref ARM_I2C_GetCapabilities
  99 *******************************************************************************************************************/
 100
 101 /**
 102 \struct     ARM_I2C_STATUS
 103 \details
 104 Structure with information about the status of the I2C.
 105
 106 The flag \em busy indicates that the driver is busy executing Master/Slave Transmit/Receive operation.
 107
 108 It is set:
 109  - when Master operation starts: after calling \ref ARM_I2C_MasterTransmit or \ref ARM_I2C_MasterReceive
 110  - when Slave operation starts: after calling \ref ARM_I2C_SlaveTransmit or \ref ARM_I2C_SlaveReceive and after being addressed by a Master as the Slave
 111
 112 It is cleared when Master/Slave operation has finished.
 113
 114 The flag \em mode indicates the current mode which is Master when Master Transmit/Receive is active or Slave otherwise.
 115
 116 The flag \em direction indicates either Transmitter or Receiver mode. It is updated during Master/Slave operation when the Slave is addressed by a Master.
 117
 118 The flag \em general_call indicates a General call (address \token{0}) when in Slave mode.
 119
 120 The flag \em arbitration_lost indicates that the Master has lost arbitration. The current Master operation is aborted.
 121
 122 The flag \em bus_error indicates that a bus error has been detected. The current Master/Slave operation is aborted.
 123
 124 <b>Returned by:</b>
 125   - \ref ARM_I2C_GetStatus
 126 *******************************************************************************************************************/
 127
 128 /**
 129 \typedef    ARM_I2C_SignalEvent_t
 130 \details
 131 Provides the typedef for the callback function \ref ARM_I2C_SignalEvent.
 132
 133 <b>Parameter for:</b>
 134   - \ref ARM_I2C_Initialize
 135 *******************************************************************************************************************/
 136
 137 /**
 138 \defgroup I2C_events I2C Events
 139 \ingroup i2c_interface_gr
 140 \brief The I2C driver generates call back events that are notified via the function \ref ARM_I2C_SignalEvent.
 141 \details
 142 This section provides the event values for the \ref ARM_I2C_SignalEvent callback function.
 143
 144 The following call back notification events are generated:
 145 @{
 146 \def  ARM_I2C_EVENT_TRANSFER_DONE
 147 \def  ARM_I2C_EVENT_TRANSFER_INCOMPLETE
 148 \def  ARM_I2C_EVENT_SLAVE_TRANSMIT
 149 \def  ARM_I2C_EVENT_SLAVE_RECEIVE
 150 \def  ARM_I2C_EVENT_ADDRESS_NACK
 151 \def  ARM_I2C_EVENT_GENERAL_CALL
 152 \def  ARM_I2C_EVENT_ARBITRATION_LOST
 153 \def  ARM_I2C_EVENT_BUS_ERROR
 154 \def  ARM_I2C_EVENT_BUS_CLEAR
 155 @}
 156 */
 157
 158
 159 //
 160 //  Functions
 161 //
 162
 163 ARM_DRIVER_VERSION ARM_I2C_GetVersion (void)  {
 164   return { 0, 0 };
 165 };
 166 /**
 167 \fn       ARM_DRIVER_VERSION ARM_I2C_GetVersion (void)
 168 \details
 169 The function \b ARM_I2C_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
 170  - API version is the version of the CMSIS-Driver specification used to implement this driver.
 171  - Driver version is source code version of the actual driver implementation.
 172
 173 Example:
 174 \code
 175 extern ARM_DRIVER_I2C Driver_I2C0;
 176 ARM_DRIVER_I2C *drv_info;
 177
 178 void setup_i2c (void)  {
 179   ARM_DRIVER_VERSION  version;
 180
 181   drv_info = &Driver_I2C0;
 182   version = drv_info->GetVersion ();
 183   if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
 184     // error handling
 185     return;
 186   }
 187 }
 188 \endcode
 189 *******************************************************************************************************************/
 190
 191 ARM_I2C_CAPABILITIES ARM_I2C_GetCapabilities (void)  {
 192   return { 0 };
 193 };
 194 /**
 195 \fn       ARM_I2C_CAPABILITIES ARM_I2C_GetCapabilities (void)
 196 \details
 197 The function \b ARM_I2C_GetCapabilities returns information about capabilities of this driver implementation.
 198 The data fields of the struct \ref ARM_I2C_CAPABILITIES encodes the driver capabilities.
 199
 200 Example:
 201 \code
 202 extern ARM_DRIVER_I2C Driver_I2C0;
 203 ARM_DRIVER_I2C *drv_info;
 204
 205 void read_capabilities (void)  {
 206   ARM_I2C_CAPABILITIES drv_capabilities;
 207
 208   drv_info = &Driver_I2C0;
 209   drv_capabilities = drv_info->GetCapabilities ();
 210   // interrogate capabilities
 211
 212 }
 213 \endcode
 214 *******************************************************************************************************************/
 215
 216 int32_t ARM_I2C_Initialize (ARM_I2C_SignalEvent_t cb_event) {
 217   return ARM_DRIVER_OK;
 218 };
 219 /**
 220 \fn       int32_t ARM_I2C_Initialize (ARM_I2C_SignalEvent_t cb_event)
 221 \details
 222 The function \b ARM_I2C_Initialize initializes the I2C interface.
 223 It is called when the middleware component starts operation.
 224
 225 The function performs the following operations:
 226   - Initializes and the I/O resources for the I2C interface.
 227   - Registers the \ref ARM_I2C_SignalEvent callback function.
 228
 229 The parameter \em cb_event is a pointer to the \ref ARM_I2C_SignalEvent callback function.
 230 Use a NULL pointer when no callback events are required.
 231
 232 Can be called multiple times. If the peripheral is already initialized the function performs no operation and
 233 returns with \ref ARM_DRIVER_OK. Refer to \ref CallSequence for more information.
 234
 235 \sa ARM_I2C_PowerControl
 236 \sa ARM_I2C_Uninitialize
 237
 238 \b Example:
 239  - refer to \ref i2c_example "Example Code"
 240
 241 *******************************************************************************************************************/
 242
 243 int32_t ARM_I2C_Uninitialize (void)  {
 244   return ARM_DRIVER_OK;
 245 };
 246 /**
 247 \fn       int32_t ARM_I2C_Uninitialize (void)
 248 \details
 249 The function \b ARM_I2C_Uninitialize releases the I/O resources of I2C interface.
 250
 251 It is called when the middleware component stops operation and releases the I/O resources used by the I2C interface.
 252 Refer to \ref CallSequence for more information.
 253
 254 \sa ARM_I2C_Initialize
 255 \sa ARM_I2C_PowerControl
 256
 257 *******************************************************************************************************************/
 258
 259 int32_t ARM_I2C_PowerControl (ARM_POWER_STATE state)  {
 260   return ARM_DRIVER_OK;
 261 };
 262 /**
 263 \fn int32_t ARM_I2C_PowerControl (ARM_POWER_STATE state)
 264 \details
 265 The function \b ARM_I2C_PowerControl operates the power modes of the I2C interface.
 266
 267 The parameter \em state can have the following values:
 268   - \ref ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA.
 269                           Can be called multiple times. If the peripheral is already in this mode,
 270                                                   then the function performs no operation and returns with \ref ARM_DRIVER_OK.
 271   - \ref ARM_POWER_LOW : may use power saving. Returns \ref ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
 272   - \ref ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
 273
 274 Refer to \ref CallSequence for more information.
 275
 276 \sa ARM_I2C_Initialize
 277 \sa ARM_I2C_Uninitialize
 278
 279 *******************************************************************************************************************/
 280
 281 int32_t ARM_I2C_MasterTransmit (uint32_t addr, const uint8_t *data, uint32_t num, bool xfer_pending)  {
 282   return ARM_DRIVER_OK;
 283 };
 284 /**
 285 \fn int32_t ARM_I2C_MasterTransmit (uint32_t addr, const uint8_t *data, uint32_t num, bool xfer_pending)
 286 \details
 287 This function \b ARM_I2C_MasterTransmit transmits data as Master to the selected Slave.
 288
 289 The operation consists of:
 290  - Master generates START condition
 291  - Master addresses the Slave as Master Transmitter
 292  - Master transmits data to the addressed Slave
 293  - Master generates STOP condition (if \em xfer_pending is "false")
 294
 295 The parameter \em addr is the address of the slave to transmit the data to. The value can be ORed with \ref ARM_I2C_ADDRESS_10BIT to
 296 identify a 10-bit address value. \n
 297 The parameter \em data and \em num specify the address of a data buffer and the number of bytes to transmit. \n
 298 Set the parameter \em xfer_pending to 'true' if another transfer operation follows. With \em xfer_pending set to 'false' a STOP condition is generated.
 299
 300 The function is non-blocking and returns as soon as the driver has started the operation.
 301 During the operation it is not allowed to call any Master function again. Also the data buffer must stay allocated and the contents of data must not be modified.
 302 When transmit operation has finished the \ref ARM_I2C_EVENT_TRANSFER_DONE event is generated.
 303 When not all the data is transferred then the \ref ARM_I2C_EVENT_TRANSFER_INCOMPLETE flag is set at the same time.
 304
 305 Number of data bytes transmitted and acknowledged is returned by the function \ref ARM_I2C_GetDataCount during and after the operation has finished.
 306
 307 The operation is aborted in the following cases (\ref ARM_I2C_EVENT_TRANSFER_DONE event is generated together with):
 308  - selected slave has not acknowledged the address: \ref ARM_I2C_EVENT_ADDRESS_NACK event
 309  - arbitration has been lost: \ref ARM_I2C_EVENT_ARBITRATION_LOST event
 310  - bus error has been detected: \ref ARM_I2C_EVENT_BUS_ERROR event
 311
 312 Status can be monitored by calling the \ref ARM_I2C_GetStatus and checking the flags.
 313
 314 Transmit operation can be aborted also by calling \ref ARM_I2C_Control with the parameter \em control \ref ARM_I2C_ABORT_TRANSFER.
 315 *******************************************************************************************************************/
 316
 317 int32_t ARM_I2C_MasterReceive (uint32_t addr, uint8_t *data, uint32_t num, bool xfer_pending)  {
 318   return ARM_DRIVER_OK;
 319 };
 320 /**
 321 \fn int32_t ARM_I2C_MasterReceive (uint32_t addr, uint8_t *data, uint32_t num, bool xfer_pending)
 322 \details
 323 This function \b ARM_I2C_MasterReceive is used to receive data as Master from the selected Slave.
 324
 325 The operation consists of:
 326  - Master generates START condition
 327  - Master addresses the Slave as Master Receiver
 328  - Master receives data from the addressed Slave
 329  - Master generates STOP condition (if \em xfer_pending is "false")
 330
 331 The parameter \em addr is the address of the slave to receive the data from. The value can be ORed with \ref ARM_I2C_ADDRESS_10BIT to
 332 identify a 10-bit address value. \n
 333 The parameter \em data and \em num specify the address of a data buffer and the number of bytes to receive. \n
 334 Set the parameter \em xfer_pending to 'true' if another transfer operation follows. With \em xfer_pending set to 'false' a STOP condition is generated.
 335
 336 The function is non-blocking and returns as soon as the driver has started the operation.
 337 During the operation it is not allowed to call any Master function again. Also the data buffer must stay allocated.
 338 When receive operation has finished the \ref ARM_I2C_EVENT_TRANSFER_DONE event is generated.
 339 When not all the data is transferred then the \ref ARM_I2C_EVENT_TRANSFER_INCOMPLETE flag is set at the same time.
 340
 341 Number of data bytes received is returned by the function \ref ARM_I2C_GetDataCount during and after the operation has finished.
 342
 343 The operation is aborted in the following cases (\ref ARM_I2C_EVENT_TRANSFER_DONE event is generated together with):
 344  - selected slave has not acknowledged the address: \ref ARM_I2C_EVENT_ADDRESS_NACK event
 345  - arbitration has been lost: \ref ARM_I2C_EVENT_ARBITRATION_LOST event
 346  - bus error has been detected: \ref ARM_I2C_EVENT_BUS_ERROR event
 347
 348 Status can be monitored by calling the \ref ARM_I2C_GetStatus and checking the flags.
 349
 350 Receive operation can be aborted also by calling \ref ARM_I2C_Control with the parameter \em control = \ref ARM_I2C_ABORT_TRANSFER.
 351 *******************************************************************************************************************/
 352
 353 int32_t ARM_I2C_SlaveTransmit (const uint8_t *data, uint32_t num)  {
 354   return ARM_DRIVER_OK;
 355 };
 356 /**
 357 \fn int32_t ARM_I2C_SlaveTransmit (const uint8_t *data, uint32_t num)
 358 \details
 359 This function \b ARM_I2C_SlaveTransmit is used to transmit data as Slave to the Master.
 360
 361 The parameter \em data is a pointer to the data to transmit. \n
 362 The parameter \em num specifies the number of bytes to transmit.
 363
 364 The function is non-blocking and returns as soon as the driver has registered the operation.
 365 The actual operation will start after being addressed by the master as a Slave Transmitter. If the operation has not been registered at that point the \ref ARM_I2C_EVENT_SLAVE_TRANSMIT event is generated.
 366 The same event is also generated if the operation has finished (specified number of bytes transmitted) but more data is requested by the master.
 367
 368 It is not allowed to call this function again if the operation has started until it finishes. Also the data buffer must stay allocated and the contents of data must not be modified.
 369 When transmit operation has finished the \ref ARM_I2C_EVENT_TRANSFER_DONE event is generated.
 370 When not all the data is transferred then the \ref ARM_I2C_EVENT_TRANSFER_INCOMPLETE flag is set at the same time.
 371
 372 Number of data bytes transmitted is returned by the function \ref ARM_I2C_GetDataCount during and after the operation has finished.
 373
 374 In case that a General call has been detected the \ref ARM_I2C_EVENT_GENERAL_CALL flag is indicated together with the \ref ARM_I2C_EVENT_TRANSFER_DONE event (also with \ref ARM_I2C_EVENT_SLAVE_TRANSMIT event).
 375
 376 In case that bus error has been detected then the operation is aborted and the \ref ARM_I2C_EVENT_BUS_ERROR event is generated together with \ref ARM_I2C_EVENT_TRANSFER_DONE.
 377
 378 Slave will only respond to its own address (or General call if enabled) that is specified by calling \ref ARM_I2C_Control with \ref ARM_I2C_OWN_ADDRESS as control parameter.
 379 Using address \token{0} disables the slave.
 380
 381 Status can be monitored by calling the \ref ARM_I2C_GetStatus and checking the flags.
 382
 383 Transmit operation can be canceled or aborted by calling \ref ARM_I2C_Control with the parameter \em control = \ref ARM_I2C_ABORT_TRANSFER.
 384 *******************************************************************************************************************/
 385
 386 int32_t ARM_I2C_SlaveReceive (uint8_t *data, uint32_t num)  {
 387   return ARM_DRIVER_OK;
 388 };
 389 /**
 390 \fn int32_t ARM_I2C_SlaveReceive (uint8_t *data, uint32_t num)
 391 \details
 392 This function \b ARM_I2C_SlaveReceive receives data as Slave from the Master.
 393
 394 The parameter \em data is a pointer to the data to receive. \n
 395 The parameter \em num specifies the number of bytes to receive.
 396
 397 The function is non-blocking and returns as soon as the driver has registered the operation.
 398 The actual operation will start after being addressed by the master as a Slave Receiver. If the operation has not been registered at that point the \ref ARM_I2C_EVENT_SLAVE_RECEIVE event is generated.
 399
 400 It is not allowed to call this function again if the operation has started until it finishes. Also the data buffer must stay allocated.
 401 When receive operation has finished the \ref ARM_I2C_EVENT_TRANSFER_DONE event is generated.
 402 When not all the data is transferred then the \ref ARM_I2C_EVENT_TRANSFER_INCOMPLETE flag is set at the same time.
 403
 404 Number of data bytes received and acknowledged is returned by the function \ref ARM_I2C_GetDataCount during and after the operation has finished.
 405
 406 In case that a General call has been detected the \ref ARM_I2C_EVENT_GENERAL_CALL flag is indicated together with the \ref ARM_I2C_EVENT_TRANSFER_DONE event (also with \ref ARM_I2C_EVENT_SLAVE_RECEIVE event).
 407
 408 In case that bus error has been detected then the operation is aborted and the \ref ARM_I2C_EVENT_BUS_ERROR event is generated together with \ref ARM_I2C_EVENT_TRANSFER_DONE.
 409
 410 Slave will only respond to its own address (or General call if enabled) that is specified by calling \ref ARM_I2C_Control with \ref ARM_I2C_OWN_ADDRESS as control parameter.
 411 Using address \token{0} disables the slave.
 412
 413 Status can be monitored by calling the \ref ARM_I2C_GetStatus and checking the flags.
 414
 415 Receive operation can be canceled or aborted by calling \ref ARM_I2C_Control with the parameter \em control = \ref ARM_I2C_ABORT_TRANSFER.
 416 *******************************************************************************************************************/
 417
 418 int32_t ARM_I2C_GetDataCount (void)  {
 419   return 0;
 420 }
 421 /**
 422 \fn int32_t ARM_I2C_GetDataCount (void)
 423 \details
 424 The function \b ARM_I2C_GetDataCount returns the number of currently transferred data bytes during and after:
 425  - \ref ARM_I2C_MasterTransmit : number of data bytes transmitted and acknowledged
 426  - \ref ARM_I2C_MasterReceive : number of data bytes received
 427  - \ref ARM_I2C_SlaveTransmit : number of data bytes transmitted
 428  - \ref ARM_I2C_SlaveReceive : number of data bytes received and acknowledged
 429
 430 When the Slave is not yet addressed by the Master then \token{-1} is returned.
 431 *****************************************************************************************************************/
 432
 433 int32_t ARM_I2C_Control (uint32_t control, uint32_t arg)  {
 434   return ARM_DRIVER_OK;
 435 }
 436 /**
 437 \fn int32_t ARM_I2C_Control (uint32_t control, uint32_t arg)
 438 \details
 439 The function \b ARM_I2C_Control operates the I2C interface and executes various operations.
 440
 441 The parameter \em control specifies various operations as listed in the table below.  \n
 442 The parameter \em arg provides, depending on the operation,  additional information. \n
 443
 444 Parameter \em control            | Operation
 445 :--------------------------------|:--------------------------------------------
 446 \ref ARM_I2C_OWN_ADDRESS         | Set Own Slave Address; \em arg = slave address
 447 \ref ARM_I2C_BUS_SPEED           | Set Bus Speed; \em arg = bus speed
 448 \ref ARM_I2C_BUS_CLEAR           | Clear the bus by sending nine clock pulses
 449 \ref ARM_I2C_ABORT_TRANSFER      | Aborts the data transfer between Master and Slave for Transmit or Receive
 450
 451 <b>Set Own Slave Address</b>
 452
 453 After initialization, the I2C Device has no slave address assigned and does not accept any requests from
 454 an I2C Master.
 455
 456 The \em control operation \ref ARM_I2C_OWN_ADDRESS sets the slave address with the parameter \em arg.
 457 The slave address can be ORed with \ref ARM_I2C_ADDRESS_10BIT to indicate a 10-bit address.
 458
 459 The slave address can be ORed with \ref ARM_I2C_ADDRESS_GC to indicate that the slave accepts a General Call.
 460 If the slave address value is only \ref ARM_I2C_ADDRESS_GC, then the slave only accepts a General Call.
 461
 462 The slave address value \token{0} disables Slave mode and clears any assigned slave address.
 463
 464 **Examples:**
 465
 466 Set the Slave address value \token{0x45} as 7-bit address.
 467 \code
 468   I2Cdrv->Control      (ARM_I2C_OWN_ADDRESS, 0x45);
 469 \endcode
 470
 471 Set the Slave address value \token{0x135} as 10-bit address and accept a General Call.
 472 \code
 473   I2Cdrv->Control      (ARM_I2C_OWN_ADDRESS, 0x135 | ARM_I2C_ADDRESS_10BIT | ARM_I2C_ADDRESS_GC);
 474 \endcode
 475
 476 <b>Bus Speed</b>
 477
 478 The \em control operation \ref ARM_I2C_BUS_SPEED sets the bus speed using the parameter \em arg.
 479
 480 Parameter \em arg                | Bus Speed
 481 :--------------------------------|:--------------------------------------------
 482 \ref ARM_I2C_BUS_SPEED_STANDARD  | Standard Speed to (\token{100 kHz})
 483 \ref ARM_I2C_BUS_SPEED_FAST      | Fast Speed  (\token{400kHz})
 484 \ref ARM_I2C_BUS_SPEED_FAST_PLUS | Fast + Speed (\token{1MHz})
 485 \ref ARM_I2C_BUS_SPEED_HIGH      | High Speed  (\token{3.4MHz})
 486
 487 **Example:**
 488
 489 \code
 490   I2Cdrv->Control      (ARM_I2C_BUS_SPEED, I2C_BUS_SPEED_FAST);
 491 \endcode
 492 *****************************************************************************************************************/
 493
 494 ARM_I2C_STATUS ARM_I2C_GetStatus (void)  {
 495   return { 0 };
 496 }
 497 /**
 498 \fn ARM_I2C_STATUS ARM_I2C_GetStatus (void)
 499 \details
 500 The function \b ARM_I2C_GetStatus returns the current I2C interface status.
 501
 502 Refer to \ref ARM_I2C_STATUS for details.
 503 *****************************************************************************************************************/
 504
 505 void ARM_I2C_SignalEvent (uint32_t event)  {
 506   // function body
 507 }
 508 /**
 509 \fn void ARM_I2C_SignalEvent (uint32_t event)
 510 \details
 511 The function \b ARM_I2C_SignalEvent is a callback function registered by the function \ref ARM_I2C_Initialize..
 512 It is called by the I2C driver to notify the application about \ref I2C_events occurred during operation.
 513
 514 The parameter \a event indicates one or more events that occurred during driver operation.
 515 Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
 516
 517 The following events can be generated:
 518
 519 Parameter \em event                       |     Bit   | Description
 520 :---------------------------------------- |:---------:|:----------------------------------------------------------
 521 \ref ARM_I2C_EVENT_TRANSFER_DONE          | 1UL&nbsp;<<&nbsp;0  | Occurs after Master/Slave Transmit/Receive operation has finished.
 522 \ref ARM_I2C_EVENT_TRANSFER_INCOMPLETE    | 1UL << 1  | Occurs together with \ref ARM_I2C_EVENT_TRANSFER_DONE when less data is transferred then requested.
 523 \ref ARM_I2C_EVENT_SLAVE_TRANSMIT         | 1UL << 2  | Occurs when addressed as Slave Transmitter and \ref ARM_I2C_SlaveTransmit has not been started.
 524 \ref ARM_I2C_EVENT_SLAVE_RECEIVE          | 1UL << 3  | Occurs when addressed as Slave Receiver and \ref ARM_I2C_SlaveReceive has not been started.
 525 \ref ARM_I2C_EVENT_ADDRESS_NACK           | 1UL << 4  | Occurs in master mode when address is not acknowledged from slave.
 526 \ref ARM_I2C_EVENT_GENERAL_CALL           | 1UL << 5  | Indicates General Call in slave mode together with \ref ARM_I2C_EVENT_TRANSFER_DONE, \ref ARM_I2C_EVENT_SLAVE_TRANSMIT and \ref ARM_I2C_EVENT_SLAVE_RECEIVE.
 527 \ref ARM_I2C_EVENT_ARBITRATION_LOST       | 1UL << 6  | Occurs in master mode when arbitration is lost.
 528 \ref ARM_I2C_EVENT_BUS_ERROR              | 1UL << 7  | Occurs when bus error is detected.
 529 \ref ARM_I2C_EVENT_BUS_CLEAR              | 1UL << 8  | Occurs after \ref ARM_I2C_BUS_CLEAR Control operation has finished.
 530
 531 **************************************************************************************************************************/
 532
 533
 534 /**
 535 \defgroup i2c_control_gr I2C Control Codes
 536 \ingroup i2c_interface_gr
 537 \brief Many parameters of the I2C driver are configured using the \ref ARM_I2C_Control function.
 538 @{
 539 \details
 540 The various I2C control codes define:
 541   - \ref i2c_control_codes           specify operation parameters and various controls
 542   - \ref i2c_bus_speed_ctrls         specify the I2C bus speed
 543
 544 Refer to the \ref ARM_I2C_Control function for further details.
 545 */
 546
 547 /**
 548 \defgroup i2c_control_codes I2C Control Codes
 549 \ingroup i2c_control_gr
 550 \brief Specify operation parameters and various controls.
 551 \details
 552 @{
 553 \def ARM_I2C_OWN_ADDRESS
 554 \sa ARM_I2C_Control
 555 \def ARM_I2C_BUS_SPEED
 556 Speed is specified using the following values: \ref i2c_bus_speed_ctrls
 557 \sa ARM_I2C_Control
 558 \def ARM_I2C_BUS_CLEAR
 559 \sa ARM_I2C_Control
 560 \def ARM_I2C_ABORT_TRANSFER
 561 \sa ARM_I2C_Control
 562 @}
 563 */
 564
 565 /**
 566 \defgroup i2c_bus_speed_ctrls I2C Bus Speed
 567 \ingroup i2c_control_gr
 568 \brief Specify the I2C bus speed.
 569 \details
 570 @{
 571 \def ARM_I2C_BUS_SPEED_STANDARD
 572 \sa ARM_I2C_Control
 573 \def ARM_I2C_BUS_SPEED_FAST
 574 \sa ARM_I2C_Control
 575 \def ARM_I2C_BUS_SPEED_FAST_PLUS
 576 \sa ARM_I2C_Control
 577 \def ARM_I2C_BUS_SPEED_HIGH
 578 \sa ARM_I2C_Control
 579 @}
 580 */
 581 /**
 582 @}
 583 */
 584
 585 /**
 586 \defgroup i2c_address_flags I2C Address Flags
 587 \ingroup i2c_interface_gr
 588 \brief Specify address flags
 589 \details
 590 Specifies the address type for the functions \ref ARM_I2C_MasterReceive, \ref ARM_I2C_MasterTransmit and \ref ARM_I2C_OWN_ADDRESS.
 591 @{
 592 \def ARM_I2C_ADDRESS_10BIT
 593 \sa ARM_I2C_OWN_ADDRESS
 594 \sa ARM_I2C_MasterTransmit
 595 \sa ARM_I2C_MasterReceive
 596 \def ARM_I2C_ADDRESS_GC
 597 \sa ARM_I2C_OWN_ADDRESS
 598 @}
 599 */
 600
 601
 602 /**
 603 @}
 604 */
 605 // End I2C Interface