1 /*++ 2 3 Copyright (c) 2004 - 2014, Intel Corporation. All rights reserved.<BR> 4 5 6 This program and the accompanying materials are licensed and made available under 7 8 the terms and conditions of the BSD License that accompanies this distribution. 9 10 The full text of the license may be found at 11 12 http://opensource.org/licenses/bsd-license.php. 13 14 15 16 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 17 18 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 19 20 21 22 23 24 \section I2cDriverStack I2C Driver Stack 25 26 The following is a representation of the I<sup>2</sup>C (I2C) 27 driver stack and an I2C bus layout. 28 29 <code><pre> 30 +-----------------+ 31 | Application | 32 +-----------------+ 33 | 34 | Third Party or UEFI 35 | 36 V 37 +--------+ +-----------------+ 38 | Slave | | Third Party | 39 | Driver | | I2C Device | 40 | | | Driver | 41 +--------+ +-----------------+ 42 | | 43 | BUS | 44 | | 45 | V 46 | +-----------------+ 47 | | I2C Bus Driver |------------------. 48 | +-----------------+ | 49 | | | 50 | HOST | BUS | 51 | | CONFIGURATION | 52 SLAVE | V MANAGEMENT | ACPI 53 | +-----------------+ | 54 | | I2C Host Driver |----------. | 55 | +-----------------+ | | 56 | | | | 57 | MASTER | V V 58 | | +-------=-------------+ 59 | V | I2C Platform Driver | 60 | +-----------------+ +---------------------+ 61 `------>| I2C Port Driver | | | 62 +-----------------+ | | 63 | | | 64 Software | | | 65 -------------------------------------------------- 66 Hardware | | | 67 | | | 68 V | | 69 +-----------------+ | | 70 | I2C Controller | | | 71 +-----------------+ | | 72 | | | 73 ----------------------- | | 74 I2C Bus | | | 75 | +------------+ | | 76 +----| High speed | | | 77 | | I2C device | | | 78 | | 0x01 | | | 79 | +------------+ | | 80 | | | 81 +---------+ 0 | | 82 | Switch |<------------------` | 83 +---------+ 1 | 84 | | 85 | +------------+ | 86 +----| Fast speed | | 87 | | I2C device | | 88 | | 0x02 | | 89 | +------------+ | 90 | | 91 +-------------+ | 92 | Multiplexer |<-----------------------` 93 +-------------+ 94 0 | | 1 95 | | 96 | | 97 | | +-------------+ 98 | +----| Third Party | 99 | | | I2C Device | 100 | | | 0x03, 0x04 | 101 | | +-------------+ 102 | | 103 | 104 | +-------------+ 105 +------------| Third Party | 106 | | I2C Device | 107 | | 0x03, 0x04 | 108 | +-------------+ 109 | 110 </pre></code> 111 112 The platform hardware designer chooses the bus layout based upon 113 the platform, I2C chip and software requirements. The design uses 114 switches to truncate the bus to enable higher speed operation for a 115 subset of devices which are placed closer to the controller. When the 116 switch is on, the extended bus must operate at a lower speed. The 117 design uses multiplexer to create separate address spaces enabling 118 the use of multiple devices which would otherwise have conflicting 119 addresses. See the 120 <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C 121 Specification</a> for more details. 122 123 N.B. Some operating systems may prohibit the changing of switches 124 and multiplexers in the I2C bus. In this case the platform hardware 125 and software designers must select a single I2C bus configuration 126 consisting of constant input values for the switches and multiplexers. 127 The platform software designer must then ensure that this I2C bus 128 configuration is enabled prior to passing control to the operating 129 system. 130 131 The platform hardware designer needs to provide the platform software 132 designer the following data for each I2C bus: 133 134 1. Which controller controls this bus 135 136 2. A list of logic blocks contained in one or more I2C devices: 137 138 a. I2C device which contains this logic block 139 140 b. Logic block slave address 141 142 c. Logic block name 143 144 3. For each configuration of the switches and multiplexer 145 146 a. What is the maximum speed of operation 147 148 b. What devices are accessible 149 150 4. The settings for the switches and multiplexers when control is 151 given to the operating system. 152 153 \section ThirdPartyI2cDrivers Third Party I2C Drivers 154 155 This layer is I2C chip specific but platform and host controller 156 independent. 157 158 Third party I2C driver writers, typically silicon vendors, need 159 to provide: 160 161 1. The device path node data that is used to select their 162 driver. 163 164 2. The order for the blocks of logic that get referenced 165 by the entries in the slave address array. 166 167 3. The hardware version of the I2C device, this value is passed 168 to the third party I2C driver to enable it to perform work 169 arounds for the specific hardware version. This value should 170 match the value in the ACPI _HRV tag. 171 172 The third party I2C driver uses relative addressing to abstract 173 the platform specific details of the I2C device. Using an 174 example I2C device containing an accelerometer and a magnetometer 175 which consumes two slave addresses, one for each logic block. The 176 third party I2C driver writer may choose to write two drivers, one 177 for each block of logic, in which case each driver refers to the 178 single I2C slave address using the relative value of zero (0). 179 However if the third party I2C driver writer chooses to write a 180 single driver which consumes multiple slave addresses then the 181 third party I2C driver writer needs to convey the order of the 182 I2C slave address entries in the slave address array to the 183 platform software designer. For the example: 184 185 0: Accelerometer 186 187 1: Magnetometer 188 189 The platform hardware designer picks the actual slave addresses 190 from the I2C device's data sheet and provides this information 191 to the platform software designer. The platform software designer 192 then places the slave addresses into the slave address array in the 193 order specified by the third party I2C driver writer. The third 194 party driver I2C writer then indirectly references this array by 195 specifying the index value as the relative slave address. The 196 relative value always starts at zero (0) and its maximum value is 197 the number of entries in slave address array minus one. 198 199 The slave address is specified as a 32-bit integer to allow room 200 for future slave address expansion. Only the port driver knows 201 the maximum slave address value. All other drivers and 202 applications must look for the EFI_NOT_FOUND status for the 203 indication that the maximum slave address was exceeded. 204 205 \section I2cBusDriver I2C Bus Driver 206 207 This layer is platform, host controller, and I2C chip independent. 208 209 The I2C bus driver creates a handle for each of the I2C devices 210 described within the platform driver. The I2C controller's device 211 path is extended with the device path node provided by the platform 212 driver and attached to the handle. The third party I2C device driver 213 uses the device path to determine if it may connect. For ACPI nodes, 214 the third party I2C driver should use the CID or CidString value. 215 216 The I2C bus driver validates the relative address for the I2C device 217 and then converts the relative value to an actual I2C slave address. 218 The request is then passed to the I2C host driver. 219 220 \section I2cHostDriver I2C Host Driver 221 222 This layer is platform, host controller, and I2C chip independent. 223 224 N.B. For proper operation of the I2C bus, only the I2C bus driver 225 and the I2C test application should connect to the I2C host driver 226 via the EFI_I2C_HOST_DRIVER_PROTOCOL. 227 228 The I2C host driver may access any device on the I2C bus. The I2C 229 host driver has the following responsibilities: 230 231 1. Limits the number of requests to the I2C port driver to one. 232 The I2C host driver holds on to additional requests until the 233 I2C port driver is available to process the request. The I2C 234 requests are issued in FIFO order to the I2C port driver. 235 236 2. Enable the proper I2C bus configuration before starting the 237 I2C request on the I2C port driver 238 239 I2C devices are addressed as the tuple: BusConfiguration:SlaveAddress. 240 I2C bus configuration zero (0) is the portion of the I2C bus that 241 connects to the host controller. The bus configuration specifies 242 the control values for the switches and multiplexers in the I2C bus. 243 After the switches and multiplexers are properly configured, the I2C 244 controller uses the slave address to access the requested I2C device. 245 246 Since the I2C driver stack supports asynchronous operations this 247 layer maintains a queue of I2C requests until the I2C controller 248 is available them. When a request reaches the head of the queue 249 the necessary bus configuration is enabled and then the request 250 is sent to the I2C port driver. 251 252 \section I2cPortDriver I2C Port Driver 253 254 This layer is I2C controller specific but platform independent. 255 256 This layer manipulates the I2C controller to perform an operation 257 on the I2C bus. This layer does not configure the I2C bus so it 258 is up to the caller to ensure that the I2C bus is in the proper 259 configuration before issuing the I2C request. 260 261 This layer typically needs the following information: 262 263 1. Host controller address 264 2. Controller's input clock frequency 265 266 Depending upon the I2C controller, more data may be necessary. 267 This layer may use any method to get these values: hard coded 268 values, PCD values, or may choose to communicate with the platform 269 layer using an undefined mechanism to get these values. 270 271 If the I2C port driver requires data from the platform driver then 272 the I2C port driver writer needs to provide the platform interface 273 details to the platform software designer. 274 275 \section I2cPlatformDriver I2C Platform Driver 276 277 When enabling access to I2C devices within UEFI, this driver 278 installs the EFI_I2C_ACPI_PROTOCOL to provide the I2C device 279 descriptions to the I2C bus driver using the EFI_I2C_DEVICE 280 structure. These descriptions include the bus configuration 281 number required for the I2C device, the slave address array 282 and the device path. 283 284 The EFI_I2C_BUS_CONFIGURATION_MANAGEMENT protocol is optional. 285 This protocol needs to be specified under the following conditions: 286 287 1. The I2C bus must operate at a frequency greater than 100 KHz 288 2. The I2C bus contains switches or multiplexers. 289 290 The EFI_I2C_BUS_CONFIGURATION_MANAGEMENT protocol enables the 291 I2C host driver to call into the I2C platform driver to enable 292 a specific I2C bus configuration and set its maximum clock speed. 293 294 The platform software designer collects the data requirements 295 from third party I2C driver writers, the I2C controller 296 driver writer, the EFI_I2C_ACPI_PROTOCOL and 297 EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL. The platform 298 software designer gets the necessary data from the platform 299 hardware designer. The platform software designer then builds 300 the data structures and implements the necessary routines to 301 construct the I2C platform driver. 302 303 \section I2cSwitches Switches and Multiplexers 304 305 There are some I2C switches and I2C multiplexers where the control 306 is done via I2C commands. When the control inputs come via the 307 same I2C bus that is being configured then the platform driver must 308 use the EFI_I2C_MASTER_PROTOCOL that is passed to the platform 309 driver. While the I2C host driver makes the call to the I2C 310 platform driver to configure the bus, the host driver keeps the 311 I2C port driver idle, to allow the I2C platform driver preform 312 the necessary configuration operations. 313 314 If however the configuration control is done via and I2C device 315 connected to a different I2C bus (host controller), then it is 316 possible for the platform software designer may choose between 317 the following: 318 319 1. Call into a third party I2C driver to manipulate the I2C 320 bus control device. 321 2. Call into the EFI_I2C_BUS_PROTOCOL if no third party I2C 322 driver exists for the I2C bus control device 323 3. Call into the EFI_I2C_HOST_PROTOCOL if the platform does 324 not expose the I2C bus control device. 325 326 **/ 327 328 #ifndef __I2C_MASTER_H__ 329 #define __I2C_MASTER_H__ 330 331 /** 332 Declare the forward references 333 334 **/ 335 typedef struct _EFI_I2C_MASTER_PROTOCOL EFI_I2C_MASTER_PROTOCOL; ///< I2C master protocol 336 337 /// 338 /// I2C device operation 339 /// 340 /// This structure provides the information necessary for an operation 341 /// on an I2C device 342 /// 343 typedef struct { 344 /// 345 /// Number of bytes to send to the I2C device 346 /// 347 UINT32 WriteBytes; 348 349 /// 350 /// Number of bytes to read, set to zero for write only operations 351 /// 352 UINT32 ReadBytes; 353 354 /// 355 /// Address of the buffer containing the data to send to the I2C device. 356 /// The WriteBuffer must be at least WriteBytes in length. 357 /// 358 UINT8 *WriteBuffer; 359 360 /// 361 /// Address of the buffer to receive data from the I2C device. Use NULL 362 /// for write only operations. The ReadBuffer must be at least ReadBytes 363 /// in length. 364 /// 365 UINT8 *ReadBuffer; 366 367 /// 368 /// Timeout for the I2C operation in 100 ns units 369 /// 370 UINT32 Timeout; 371 } EFI_I2C_REQUEST_PACKET; 372 373 374 /** 375 Set the I2C controller bus clock frequency. 376 377 This routine must be called at or below TPL_NOTIFY. 378 379 The software and controller do a best case effort of using the specified 380 frequency for the I2C bus. If the frequency does not match exactly then 381 the controller will use a slightly lower frequency to avoid 382 exceeding the operating conditions for any of the I2C devices on the bus. 383 For example if 400 KHz was specified and the controller's divide network 384 only supports 402 KHz or 398 KHz then the controller would be set to 398 385 KHz. However if the desired frequency is 400 KHz and the controller only 386 supports 1 MHz and 100 KHz then this routine would return EFI_UNSUPPORTED. 387 388 @param[in] This Address of an EFI_I2C_MASTER_PROTOCOL 389 structure 390 @param[in] BusClockHertz New I2C bus clock frequency in Hertz 391 392 @retval EFI_SUCCESS The bus frequency was set successfully. 393 @retval EFI_UNSUPPORTED The controller does not support this frequency. 394 395 **/ 396 typedef 397 EFI_STATUS 398 (EFIAPI *EFI_I2C_MASTER_BUS_FREQUENCY_SET) ( 399 IN CONST EFI_I2C_MASTER_PROTOCOL *This, 400 IN UINTN BusClockHertz 401 ); 402 403 /** 404 Reset the I2C controller and configure it for use 405 406 This routine must be called at or below TPL_NOTIFY. 407 408 The I2C controller is reset and the I2C bus frequency is set to 100 KHz. 409 410 @param[in] This Address of an EFI_I2C_MASTER_PROTOCOL 411 structure 412 413 **/ 414 typedef 415 VOID 416 (EFIAPI *EFI_I2C_MASTER_RESET) ( 417 IN CONST EFI_I2C_MASTER_PROTOCOL *This 418 ); 419 420 /** 421 Start an I2C operation on the host controller 422 423 This routine must be called at or below TPL_NOTIFY. For synchronous 424 requests this routine must be called at or below TPL_CALLBACK. 425 426 This function initiates an I2C operation on the controller. 427 428 The operation is performed by selecting the I2C device with its slave 429 address and then sending all write data to the I2C device. If read data 430 is requested, a restart is sent followed by the slave address and then 431 the read data is clocked into the I2C controller and placed in the read 432 buffer. When the operation completes, the status value is returned and 433 then the event is set. 434 435 N.B. The typical consumer of this API is the I2C host driver. 436 Extreme care must be taken by other consumers of this API to 437 prevent confusing the third party I2C drivers due to a state 438 change at the I2C device which the third party I2C drivers did 439 not initiate. I2C platform drivers may use this API within 440 these guidelines. 441 442 N.B. This API supports only one operation, no queuing support 443 exists at this layer. This API assumes that the I2C bus is in 444 the correct configuration for the I2C request. 445 446 @param[in] This Address of an EFI_I2C_MASTER_PROTOCOL 447 structure 448 @param[in] SlaveAddress Address of the device on the I2C bus. 449 @param[in] Event Event to set for asynchronous operations, 450 NULL for synchronous operations 451 @param[in] RequestPacket Address of an EFI_I2C_REQUEST_PACKET 452 structure describing the I2C operation 453 @param[out] I2cStatus Optional buffer to receive the I2C operation 454 completion status 455 456 @retval EFI_SUCCESS The operation completed successfully. 457 @retval EFI_ABORTED The request did not complete because the driver 458 was shutdown. 459 @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large. 460 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation. 461 This could indicate the slave device is not present. 462 @retval EFI_INVALID_PARAMETER RequestPacket is NULL 463 @retval EFI_INVALID_PARAMETER TPL is too high 464 @retval EFI_NOT_FOUND SlaveAddress exceeds maximum address 465 @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for 466 the event and then read status pointed to by 467 the request packet. 468 @retval EFI_NO_RESPONSE The I2C device is not responding to the 469 slave address. EFI_DEVICE_ERROR may also be 470 returned if the controller cannot distinguish 471 when the NACK occurred. 472 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation 473 @retval EFI_TIMEOUT The transaction did not complete within an internally 474 specified timeout period. 475 476 **/ 477 typedef 478 EFI_STATUS 479 (EFIAPI *EFI_I2C_MASTER_START_REQUEST) ( 480 IN CONST EFI_I2C_MASTER_PROTOCOL *This, 481 IN UINTN SlaveAddress, 482 IN EFI_EVENT Event OPTIONAL, 483 IN CONST EFI_I2C_REQUEST_PACKET *RequestPacket, 484 OUT EFI_STATUS *I2cStatus OPTIONAL 485 ); 486 487 /// 488 /// I2C master mode protocol 489 /// 490 /// This protocol manipulates the I2C host controller to perform transactions as a 491 /// master on the I2C bus using the current state of any switches or multiplexers 492 /// in the I2C bus. 493 /// 494 struct _EFI_I2C_MASTER_PROTOCOL { 495 /// 496 /// Set the clock frequency for the I2C bus 497 /// 498 EFI_I2C_MASTER_BUS_FREQUENCY_SET BusFrequencySet; 499 500 /// 501 /// Reset the I2C host controller 502 /// 503 EFI_I2C_MASTER_RESET Reset; 504 505 /// 506 /// Start an I2C transaction in master mode on the host controller 507 /// 508 EFI_I2C_MASTER_START_REQUEST StartRequest; 509 510 /// 511 /// The maximum number of bytes the I2C host controller 512 /// is able to receive from the I2C bus. 513 /// 514 UINT32 MaximumReceiveBytes; 515 516 /// 517 /// The maximum number of bytes the I2C host controller 518 /// is able to send on the I2C bus. 519 /// 520 UINT32 MaximumTransmitBytes; 521 522 /// 523 /// The maximum number of bytes in the I2C bus transaction. 524 /// 525 UINT32 MaximumTotalBytes; 526 }; 527 528 /// 529 /// GUID for the EFI_I2C_MASTER_PROTOCOL 530 /// 531 extern EFI_GUID gEfiI2cMasterProtocolGuid; 532 533 #endif // __I2C_MASTER_H__ 534