1 /** @file 2 Private data structures for the I2C DXE driver. 3 4 This file defines common data structures, macro definitions and some module 5 internal function header files. 6 7 Copyright (c) 2013, Intel Corporation. All rights reserved.<BR> 8 This program and the accompanying materials 9 are licensed and made available under the terms and conditions of the BSD License 10 which accompanies this distribution. The full text of the license may be found at 11 http://opensource.org/licenses/bsd-license.php 12 13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 15 16 **/ 17 18 #ifndef __I2C_DXE_H__ 19 #define __I2C_DXE_H__ 20 21 #include <Uefi.h> 22 #include <Library/BaseMemoryLib.h> 23 #include <Library/DebugLib.h> 24 #include <Library/DevicePathLib.h> 25 #include <Library/MemoryAllocationLib.h> 26 #include <Library/TimerLib.h> 27 #include <Library/UefiBootServicesTableLib.h> 28 #include <Library/UefiDriverEntryPoint.h> 29 #include <Library/UefiLib.h> 30 31 #include <Protocol/DriverBinding.h> 32 #include <Protocol/I2cEnumerate.h> 33 #include <Protocol/I2cHost.h> 34 #include <Protocol/I2cIo.h> 35 #include <Protocol/I2cMaster.h> 36 #include <Protocol/I2cBusConfigurationManagement.h> 37 #include <Protocol/LoadedImage.h> 38 39 #define I2C_DEVICE_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'D') 40 #define I2C_HOST_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'H') 41 #define I2C_REQUEST_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'R') 42 43 // 44 // Synchronize access to the list of requests 45 // 46 #define TPL_I2C_SYNC TPL_NOTIFY 47 48 // 49 // I2C bus context 50 // 51 typedef struct { 52 EFI_I2C_ENUMERATE_PROTOCOL *I2cEnumerate; 53 EFI_I2C_HOST_PROTOCOL *I2cHost; 54 EFI_HANDLE Controller; 55 EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath; 56 EFI_HANDLE DriverBindingHandle; 57 } I2C_BUS_CONTEXT; 58 59 // 60 // I2C device context 61 // 62 typedef struct { 63 // 64 // Structure identification 65 // 66 UINT32 Signature; 67 68 // 69 // I2c device handle 70 // 71 EFI_HANDLE Handle; 72 73 // 74 // Upper level API to support the I2C device I/O 75 // 76 EFI_I2C_IO_PROTOCOL I2cIo; 77 78 // 79 // Device path for this device 80 // 81 EFI_DEVICE_PATH_PROTOCOL *DevicePath; 82 83 // 84 // Platform specific data for this device 85 // 86 CONST EFI_I2C_DEVICE *I2cDevice; 87 88 // 89 // Context for the common I/O support including the 90 // lower level API to the host controller. 91 // 92 I2C_BUS_CONTEXT *I2cBusContext; 93 } I2C_DEVICE_CONTEXT; 94 95 #define I2C_DEVICE_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_DEVICE_CONTEXT, I2cIo, I2C_DEVICE_SIGNATURE) 96 97 // 98 // I2C Request 99 // 100 typedef struct { 101 // 102 // Signature 103 // 104 UINT32 Signature; 105 106 // 107 // Next request in the pending request list 108 // 109 LIST_ENTRY Link; 110 111 // 112 // I2C bus configuration for the operation 113 // 114 UINTN I2cBusConfiguration; 115 116 // 117 // I2C slave address for the operation 118 // 119 UINTN SlaveAddress; 120 121 // 122 // Event to set for asynchronous operations, NULL for 123 // synchronous operations 124 // 125 EFI_EVENT Event; 126 127 // 128 // I2C operation description 129 // 130 EFI_I2C_REQUEST_PACKET *RequestPacket; 131 132 // 133 // Optional buffer to receive the I2C operation completion status 134 // 135 EFI_STATUS *Status; 136 } I2C_REQUEST; 137 138 #define I2C_REQUEST_FROM_ENTRY(a) CR (a, I2C_REQUEST, Link, I2C_REQUEST_SIGNATURE); 139 140 // 141 // I2C host context 142 // 143 typedef struct { 144 // 145 // Structure identification 146 // 147 UINTN Signature; 148 149 // 150 // Current I2C bus configuration 151 // 152 UINTN I2cBusConfiguration; 153 154 // 155 // I2C bus configuration management event 156 // 157 EFI_EVENT I2cBusConfigurationEvent; 158 159 // 160 // I2C operation completion event 161 // 162 EFI_EVENT I2cEvent; 163 164 // 165 // I2C operation and I2C bus configuration management status 166 // 167 EFI_STATUS Status; 168 169 // 170 // I2C bus configuration management operation pending 171 // 172 BOOLEAN I2cBusConfigurationManagementPending; 173 174 // 175 // I2C request list maintained by I2C Host 176 // 177 LIST_ENTRY RequestList; 178 179 // 180 // Upper level API 181 // 182 EFI_I2C_HOST_PROTOCOL I2cHost; 183 184 // 185 // I2C bus configuration management protocol 186 // 187 EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL *I2cBusConfigurationManagement; 188 189 // 190 // Lower level API for I2C master (controller) 191 // 192 EFI_I2C_MASTER_PROTOCOL *I2cMaster; 193 } I2C_HOST_CONTEXT; 194 195 #define I2C_HOST_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_HOST_CONTEXT, I2cHost, I2C_HOST_SIGNATURE) 196 197 // 198 // Global Variables 199 // 200 extern EFI_COMPONENT_NAME_PROTOCOL gI2cBusComponentName; 201 extern EFI_COMPONENT_NAME2_PROTOCOL gI2cBusComponentName2; 202 extern EFI_DRIVER_BINDING_PROTOCOL gI2cBusDriverBinding; 203 204 extern EFI_COMPONENT_NAME_PROTOCOL gI2cHostComponentName; 205 extern EFI_COMPONENT_NAME2_PROTOCOL gI2cHostComponentName2; 206 extern EFI_DRIVER_BINDING_PROTOCOL gI2cHostDriverBinding; 207 208 /** 209 Start the I2C driver 210 211 This routine allocates the necessary resources for the driver. 212 213 This routine is called by I2cBusDriverStart to complete the driver 214 initialization. 215 216 @param[in] I2cBus Address of an I2C_BUS_CONTEXT structure 217 @param[in] Controller Handle to the controller 218 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. 219 220 @retval EFI_SUCCESS Driver API properly initialized 221 222 **/ 223 EFI_STATUS 224 RegisterI2cDevice ( 225 IN I2C_BUS_CONTEXT *I2cBus, 226 IN EFI_HANDLE Controller, 227 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 228 ); 229 230 /** 231 Unregister an I2C device. 232 233 This function removes the protocols installed on the controller handle and 234 frees the resources allocated for the I2C device. 235 236 @param This The pointer to EFI_DRIVER_BINDING_PROTOCOL instance. 237 @param Controller The controller handle of the I2C device. 238 @param Handle The child handle. 239 240 @retval EFI_SUCCESS The I2C device is successfully unregistered. 241 @return Others Some error occurs when unregistering the I2C device. 242 243 **/ 244 EFI_STATUS 245 UnRegisterI2cDevice ( 246 IN EFI_DRIVER_BINDING_PROTOCOL *This, 247 IN EFI_HANDLE Controller, 248 IN EFI_HANDLE Handle 249 ); 250 251 /** 252 Create a path for the I2C device 253 254 Append the I2C slave path to the I2C master controller path. 255 256 @param[in] I2cDeviceContext Address of an I2C_DEVICE_CONTEXT structure. 257 @param[in] BuildControllerNode Flag to build controller node in device path. 258 259 @retval EFI_SUCCESS The I2C device path is built successfully. 260 @return Others It is failed to built device path. 261 262 **/ 263 EFI_STATUS 264 I2cBusDevicePathAppend ( 265 IN I2C_DEVICE_CONTEXT *I2cDeviceContext, 266 IN BOOLEAN BuildControllerNode 267 ); 268 269 /** 270 Queue an I2C transaction for execution on the I2C device. 271 272 This routine must be called at or below TPL_NOTIFY. For synchronous 273 requests this routine must be called at or below TPL_CALLBACK. 274 275 This routine queues an I2C transaction to the I2C controller for 276 execution on the I2C bus. 277 278 When Event is NULL, QueueRequest() operates synchronously and returns 279 the I2C completion status as its return value. 280 281 When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS 282 indicating that the asynchronous I2C transaction was queued. The values 283 above are returned in the buffer pointed to by I2cStatus upon the 284 completion of the I2C transaction when I2cStatus is not NULL. 285 286 The upper layer driver writer provides the following to the platform 287 vendor: 288 289 1. Vendor specific GUID for the I2C part 290 2. Guidance on proper construction of the slave address array when the 291 I2C device uses more than one slave address. The I2C bus protocol 292 uses the SlaveAddressIndex to perform relative to physical address 293 translation to access the blocks of hardware within the I2C device. 294 295 @param[in] This Pointer to an EFI_I2C_IO_PROTOCOL structure. 296 @param[in] SlaveAddressIndex Index value into an array of slave addresses 297 for the I2C device. The values in the array 298 are specified by the board designer, with the 299 third party I2C device driver writer providing 300 the slave address order. 301 302 For devices that have a single slave address, 303 this value must be zero. If the I2C device 304 uses more than one slave address then the 305 third party (upper level) I2C driver writer 306 needs to specify the order of entries in the 307 slave address array. 308 309 \ref ThirdPartyI2cDrivers "Third Party I2C 310 Drivers" section in I2cMaster.h. 311 @param[in] Event Event to signal for asynchronous transactions, 312 NULL for synchronous transactions 313 @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure 314 describing the I2C transaction 315 @param[out] I2cStatus Optional buffer to receive the I2C transaction 316 completion status 317 318 @retval EFI_SUCCESS The asynchronous transaction was successfully 319 queued when Event is not NULL. 320 @retval EFI_SUCCESS The transaction completed successfully when 321 Event is NULL. 322 @retval EFI_ABORTED The request did not complete because the driver 323 binding Stop() routine was called. 324 @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too 325 large. 326 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the 327 transaction. 328 @retval EFI_INVALID_PARAMETER RequestPacket is NULL 329 @retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter 330 @retval EFI_NO_MAPPING The EFI_I2C_HOST_PROTOCOL could not set the 331 bus configuration required to access this I2C 332 device. 333 @retval EFI_NO_RESPONSE The I2C device is not responding to the slave 334 address selected by SlaveAddressIndex. 335 EFI_DEVICE_ERROR will be returned if the 336 controller cannot distinguish when the NACK 337 occurred. 338 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction 339 @retval EFI_UNSUPPORTED The controller does not support the requested 340 transaction. 341 342 **/ 343 EFI_STATUS 344 EFIAPI 345 I2cBusQueueRequest ( 346 IN CONST EFI_I2C_IO_PROTOCOL *This, 347 IN UINTN SlaveAddressIndex, 348 IN EFI_EVENT Event OPTIONAL, 349 IN EFI_I2C_REQUEST_PACKET *RequestPacket, 350 OUT EFI_STATUS *I2cStatus OPTIONAL 351 ); 352 353 /** 354 Tests to see if this driver supports a given controller. If a child device is provided, 355 it further tests to see if this driver supports creating a handle for the specified child device. 356 357 This function checks to see if the driver specified by This supports the device specified by 358 ControllerHandle. Drivers will typically use the device path attached to 359 ControllerHandle and/or the services from the bus I/O abstraction attached to 360 ControllerHandle to determine if the driver supports ControllerHandle. This function 361 may be called many times during platform initialization. In order to reduce boot times, the tests 362 performed by this function must be very small, and take as little time as possible to execute. This 363 function must not change the state of any hardware devices, and this function must be aware that the 364 device specified by ControllerHandle may already be managed by the same driver or a 365 different driver. This function must match its calls to AllocatePages() with FreePages(), 366 AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol(). 367 Since ControllerHandle may have been previously started by the same driver, if a protocol is 368 already in the opened state, then it must not be closed with CloseProtocol(). This is required 369 to guarantee the state of ControllerHandle is not modified by this function. 370 371 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 372 @param[in] ControllerHandle The handle of the controller to test. This handle 373 must support a protocol interface that supplies 374 an I/O abstraction to the driver. 375 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This 376 parameter is ignored by device drivers, and is optional for bus 377 drivers. For bus drivers, if this parameter is not NULL, then 378 the bus driver must determine if the bus controller specified 379 by ControllerHandle and the child controller specified 380 by RemainingDevicePath are both supported by this 381 bus driver. 382 383 @retval EFI_SUCCESS The device specified by ControllerHandle and 384 RemainingDevicePath is supported by the driver specified by This. 385 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and 386 RemainingDevicePath is already being managed by the driver 387 specified by This. 388 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and 389 RemainingDevicePath is already being managed by a different 390 driver or an application that requires exclusive access. 391 Currently not implemented. 392 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and 393 RemainingDevicePath is not supported by the driver specified by This. 394 **/ 395 EFI_STATUS 396 EFIAPI 397 I2cBusDriverSupported ( 398 IN EFI_DRIVER_BINDING_PROTOCOL *This, 399 IN EFI_HANDLE Controller, 400 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 401 ); 402 403 /** 404 Starts a device controller or a bus controller. 405 406 The Start() function is designed to be invoked from the EFI boot service ConnectController(). 407 As a result, much of the error checking on the parameters to Start() has been moved into this 408 common boot service. It is legal to call Start() from other locations, 409 but the following calling restrictions must be followed or the system behavior will not be deterministic. 410 1. ControllerHandle must be a valid EFI_HANDLE. 411 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned 412 EFI_DEVICE_PATH_PROTOCOL. 413 3. Prior to calling Start(), the Supported() function for the driver specified by This must 414 have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS. 415 416 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 417 @param[in] ControllerHandle The handle of the controller to start. This handle 418 must support a protocol interface that supplies 419 an I/O abstraction to the driver. 420 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This 421 parameter is ignored by device drivers, and is optional for bus 422 drivers. For a bus driver, if this parameter is NULL, then handles 423 for all the children of Controller are created by this driver. 424 If this parameter is not NULL and the first Device Path Node is 425 not the End of Device Path Node, then only the handle for the 426 child device specified by the first Device Path Node of 427 RemainingDevicePath is created by this driver. 428 If the first Device Path Node of RemainingDevicePath is 429 the End of Device Path Node, no child handle is created by this 430 driver. 431 432 @retval EFI_SUCCESS The device was started. 433 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented. 434 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 435 @retval Others The driver failded to start the device. 436 437 **/ 438 EFI_STATUS 439 EFIAPI 440 I2cBusDriverStart ( 441 IN EFI_DRIVER_BINDING_PROTOCOL *This, 442 IN EFI_HANDLE Controller, 443 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 444 ); 445 446 /** 447 Stops a device controller or a bus controller. 448 449 The Stop() function is designed to be invoked from the EFI boot service DisconnectController(). 450 As a result, much of the error checking on the parameters to Stop() has been moved 451 into this common boot service. It is legal to call Stop() from other locations, 452 but the following calling restrictions must be followed or the system behavior will not be deterministic. 453 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this 454 same driver's Start() function. 455 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid 456 EFI_HANDLE. In addition, all of these handles must have been created in this driver's 457 Start() function, and the Start() function must have called OpenProtocol() on 458 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. 459 460 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 461 @param[in] ControllerHandle A handle to the device being stopped. The handle must 462 support a bus specific I/O protocol for the driver 463 to use to stop the device. 464 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer. 465 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL 466 if NumberOfChildren is 0. 467 468 @retval EFI_SUCCESS The device was stopped. 469 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error. 470 471 **/ 472 EFI_STATUS 473 EFIAPI 474 I2cBusDriverStop ( 475 IN EFI_DRIVER_BINDING_PROTOCOL *This, 476 IN EFI_HANDLE Controller, 477 IN UINTN NumberOfChildren, 478 IN EFI_HANDLE *ChildHandleBuffer 479 ); 480 481 /** 482 Retrieves a Unicode string that is the user readable name of the driver. 483 484 This function retrieves the user readable name of a driver in the form of a 485 Unicode string. If the driver specified by This has a user readable name in 486 the language specified by Language, then a pointer to the driver name is 487 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified 488 by This does not support the language specified by Language, 489 then EFI_UNSUPPORTED is returned. 490 491 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 492 EFI_COMPONENT_NAME_PROTOCOL instance. 493 494 @param Language[in] A pointer to a Null-terminated ASCII string 495 array indicating the language. This is the 496 language of the driver name that the caller is 497 requesting, and it must match one of the 498 languages specified in SupportedLanguages. The 499 number of languages supported by a driver is up 500 to the driver writer. Language is specified 501 in RFC 4646 or ISO 639-2 language code format. 502 503 @param DriverName[out] A pointer to the Unicode string to return. 504 This Unicode string is the name of the 505 driver specified by This in the language 506 specified by Language. 507 508 @retval EFI_SUCCESS The Unicode string for the Driver specified by 509 This and the language specified by Language was 510 returned in DriverName. 511 512 @retval EFI_INVALID_PARAMETER Language is NULL. 513 514 @retval EFI_INVALID_PARAMETER DriverName is NULL. 515 516 @retval EFI_UNSUPPORTED The driver specified by This does not support 517 the language specified by Language. 518 519 **/ 520 EFI_STATUS 521 EFIAPI 522 I2cBusComponentNameGetDriverName ( 523 IN EFI_COMPONENT_NAME2_PROTOCOL *This, 524 IN CHAR8 *Language, 525 OUT CHAR16 **DriverName 526 ); 527 528 /** 529 Retrieves a Unicode string that is the user readable name of the controller 530 that is being managed by a driver. 531 532 This function retrieves the user readable name of the controller specified by 533 ControllerHandle and ChildHandle in the form of a Unicode string. If the 534 driver specified by This has a user readable name in the language specified by 535 Language, then a pointer to the controller name is returned in ControllerName, 536 and EFI_SUCCESS is returned. If the driver specified by This is not currently 537 managing the controller specified by ControllerHandle and ChildHandle, 538 then EFI_UNSUPPORTED is returned. If the driver specified by This does not 539 support the language specified by Language, then EFI_UNSUPPORTED is returned. 540 541 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 542 EFI_COMPONENT_NAME_PROTOCOL instance. 543 544 @param ControllerHandle[in] The handle of a controller that the driver 545 specified by This is managing. This handle 546 specifies the controller whose name is to be 547 returned. 548 549 @param ChildHandle[in] The handle of the child controller to retrieve 550 the name of. This is an optional parameter that 551 may be NULL. It will be NULL for device 552 drivers. It will also be NULL for a bus drivers 553 that wish to retrieve the name of the bus 554 controller. It will not be NULL for a bus 555 driver that wishes to retrieve the name of a 556 child controller. 557 558 @param Language[in] A pointer to a Null-terminated ASCII string 559 array indicating the language. This is the 560 language of the driver name that the caller is 561 requesting, and it must match one of the 562 languages specified in SupportedLanguages. The 563 number of languages supported by a driver is up 564 to the driver writer. Language is specified in 565 RFC 4646 or ISO 639-2 language code format. 566 567 @param ControllerName[out] A pointer to the Unicode string to return. 568 This Unicode string is the name of the 569 controller specified by ControllerHandle and 570 ChildHandle in the language specified by 571 Language from the point of view of the driver 572 specified by This. 573 574 @retval EFI_SUCCESS The Unicode string for the user readable name in 575 the language specified by Language for the 576 driver specified by This was returned in 577 DriverName. 578 579 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL. 580 581 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid 582 EFI_HANDLE. 583 584 @retval EFI_INVALID_PARAMETER Language is NULL. 585 586 @retval EFI_INVALID_PARAMETER ControllerName is NULL. 587 588 @retval EFI_UNSUPPORTED The driver specified by This is not currently 589 managing the controller specified by 590 ControllerHandle and ChildHandle. 591 592 @retval EFI_UNSUPPORTED The driver specified by This does not support 593 the language specified by Language. 594 595 **/ 596 EFI_STATUS 597 EFIAPI 598 I2cBusComponentNameGetControllerName ( 599 IN EFI_COMPONENT_NAME2_PROTOCOL *This, 600 IN EFI_HANDLE ControllerHandle, 601 IN EFI_HANDLE ChildHandle OPTIONAL, 602 IN CHAR8 *Language, 603 OUT CHAR16 **ControllerName 604 ); 605 606 /** 607 The user entry point for the I2C bus module. The user code starts with 608 this function. 609 610 @param[in] ImageHandle The firmware allocated handle for the EFI image. 611 @param[in] SystemTable A pointer to the EFI System Table. 612 613 @retval EFI_SUCCESS The entry point is executed successfully. 614 @retval other Some error occurs when executing this entry point. 615 616 **/ 617 EFI_STATUS 618 EFIAPI 619 InitializeI2cBus( 620 IN EFI_HANDLE ImageHandle, 621 IN EFI_SYSTEM_TABLE *SystemTable 622 ); 623 624 /** 625 This is the unload handle for I2C bus module. 626 627 Disconnect the driver specified by ImageHandle from all the devices in the handle database. 628 Uninstall all the protocols installed in the driver entry point. 629 630 @param[in] ImageHandle The drivers' driver image. 631 632 @retval EFI_SUCCESS The image is unloaded. 633 @retval Others Failed to unload the image. 634 635 **/ 636 EFI_STATUS 637 EFIAPI 638 I2cBusUnload ( 639 IN EFI_HANDLE ImageHandle 640 ); 641 642 /** 643 Release all the resources allocated for the I2C device. 644 645 This function releases all the resources allocated for the I2C device. 646 647 @param I2cDeviceContext The I2C child device involved for the operation. 648 649 **/ 650 VOID 651 ReleaseI2cDeviceContext ( 652 IN I2C_DEVICE_CONTEXT *I2cDeviceContext 653 ); 654 655 /** 656 Complete the current request 657 658 @param[in] I2cHost Address of an I2C_HOST_CONTEXT structure. 659 @param[in] Status Status of the I<sub>2</sub>C operation. 660 661 @return This routine returns the input status value. 662 663 **/ 664 EFI_STATUS 665 I2cHostRequestComplete ( 666 I2C_HOST_CONTEXT *I2cHost, 667 EFI_STATUS Status 668 ); 669 670 /** 671 Enable access to the I2C bus configuration 672 673 @param[in] I2cHostContext Address of an I2C_HOST_CONTEXT structure 674 675 @retval EFI_SUCCESS The operation completed successfully. 676 @retval EFI_ABORTED The request did not complete because the driver 677 was shutdown. 678 @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large. 679 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation. 680 This could indicate the slave device is not present. 681 @retval EFI_INVALID_PARAMETER RequestPacket is NULL 682 @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value 683 @retval EFI_NO_RESPONSE The I2C device is not responding to the 684 slave address. EFI_DEVICE_ERROR may also be 685 returned if the controller can not distinguish 686 when the NACK occurred. 687 @retval EFI_NOT_FOUND I2C slave address exceeds maximum address 688 @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for 689 the event and then read status. 690 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation 691 @retval EFI_TIMEOUT The transaction did not complete within an internally 692 specified timeout period. 693 694 **/ 695 EFI_STATUS 696 I2cHostRequestEnable ( 697 I2C_HOST_CONTEXT *I2cHost 698 ); 699 700 /** 701 Tests to see if this driver supports a given controller. If a child device is provided, 702 it further tests to see if this driver supports creating a handle for the specified child device. 703 704 This function checks to see if the driver specified by This supports the device specified by 705 ControllerHandle. Drivers will typically use the device path attached to 706 ControllerHandle and/or the services from the bus I/O abstraction attached to 707 ControllerHandle to determine if the driver supports ControllerHandle. This function 708 may be called many times during platform initialization. In order to reduce boot times, the tests 709 performed by this function must be very small, and take as little time as possible to execute. This 710 function must not change the state of any hardware devices, and this function must be aware that the 711 device specified by ControllerHandle may already be managed by the same driver or a 712 different driver. This function must match its calls to AllocatePages() with FreePages(), 713 AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol(). 714 Since ControllerHandle may have been previously started by the same driver, if a protocol is 715 already in the opened state, then it must not be closed with CloseProtocol(). This is required 716 to guarantee the state of ControllerHandle is not modified by this function. 717 718 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 719 @param[in] ControllerHandle The handle of the controller to test. This handle 720 must support a protocol interface that supplies 721 an I/O abstraction to the driver. 722 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This 723 parameter is ignored by device drivers, and is optional for bus 724 drivers. For bus drivers, if this parameter is not NULL, then 725 the bus driver must determine if the bus controller specified 726 by ControllerHandle and the child controller specified 727 by RemainingDevicePath are both supported by this 728 bus driver. 729 730 @retval EFI_SUCCESS The device specified by ControllerHandle and 731 RemainingDevicePath is supported by the driver specified by This. 732 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and 733 RemainingDevicePath is already being managed by the driver 734 specified by This. 735 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and 736 RemainingDevicePath is already being managed by a different 737 driver or an application that requires exclusive access. 738 Currently not implemented. 739 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and 740 RemainingDevicePath is not supported by the driver specified by This. 741 **/ 742 EFI_STATUS 743 EFIAPI 744 I2cHostDriverSupported ( 745 IN EFI_DRIVER_BINDING_PROTOCOL *This, 746 IN EFI_HANDLE Controller, 747 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 748 ); 749 750 /** 751 Starts a device controller or a bus controller. 752 753 The Start() function is designed to be invoked from the EFI boot service ConnectController(). 754 As a result, much of the error checking on the parameters to Start() has been moved into this 755 common boot service. It is legal to call Start() from other locations, 756 but the following calling restrictions must be followed, or the system behavior will not be deterministic. 757 1. ControllerHandle must be a valid EFI_HANDLE. 758 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned 759 EFI_DEVICE_PATH_PROTOCOL. 760 3. Prior to calling Start(), the Supported() function for the driver specified by This must 761 have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS. 762 763 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 764 @param[in] ControllerHandle The handle of the controller to start. This handle 765 must support a protocol interface that supplies 766 an I/O abstraction to the driver. 767 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This 768 parameter is ignored by device drivers, and is optional for bus 769 drivers. For a bus driver, if this parameter is NULL, then handles 770 for all the children of Controller are created by this driver. 771 If this parameter is not NULL and the first Device Path Node is 772 not the End of Device Path Node, then only the handle for the 773 child device specified by the first Device Path Node of 774 RemainingDevicePath is created by this driver. 775 If the first Device Path Node of RemainingDevicePath is 776 the End of Device Path Node, no child handle is created by this 777 driver. 778 779 @retval EFI_SUCCESS The device was started. 780 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented. 781 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 782 @retval Others The driver failded to start the device. 783 784 **/ 785 EFI_STATUS 786 EFIAPI 787 I2cHostDriverStart ( 788 IN EFI_DRIVER_BINDING_PROTOCOL *This, 789 IN EFI_HANDLE Controller, 790 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 791 ); 792 793 /** 794 Stops a device controller or a bus controller. 795 796 The Stop() function is designed to be invoked from the EFI boot service DisconnectController(). 797 As a result, much of the error checking on the parameters to Stop() has been moved 798 into this common boot service. It is legal to call Stop() from other locations, 799 but the following calling restrictions must be followed, or the system behavior will not be deterministic. 800 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this 801 same driver's Start() function. 802 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid 803 EFI_HANDLE. In addition, all of these handles must have been created in this driver's 804 Start() function, and the Start() function must have called OpenProtocol() on 805 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. 806 807 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 808 @param[in] ControllerHandle A handle to the device being stopped. The handle must 809 support a bus specific I/O protocol for the driver 810 to use to stop the device. 811 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer. 812 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL 813 if NumberOfChildren is 0. 814 815 @retval EFI_SUCCESS The device was stopped. 816 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error. 817 818 **/ 819 EFI_STATUS 820 EFIAPI 821 I2cHostDriverStop ( 822 IN EFI_DRIVER_BINDING_PROTOCOL *This, 823 IN EFI_HANDLE Controller, 824 IN UINTN NumberOfChildren, 825 IN EFI_HANDLE *ChildHandleBuffer 826 ); 827 828 /** 829 Retrieves a Unicode string that is the user readable name of the driver. 830 831 This function retrieves the user readable name of a driver in the form of a 832 Unicode string. If the driver specified by This has a user readable name in 833 the language specified by Language, then a pointer to the driver name is 834 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified 835 by This does not support the language specified by Language, 836 then EFI_UNSUPPORTED is returned. 837 838 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 839 EFI_COMPONENT_NAME_PROTOCOL instance. 840 841 @param Language[in] A pointer to a Null-terminated ASCII string 842 array indicating the language. This is the 843 language of the driver name that the caller is 844 requesting, and it must match one of the 845 languages specified in SupportedLanguages. The 846 number of languages supported by a driver is up 847 to the driver writer. Language is specified 848 in RFC 4646 or ISO 639-2 language code format. 849 850 @param DriverName[out] A pointer to the Unicode string to return. 851 This Unicode string is the name of the 852 driver specified by This in the language 853 specified by Language. 854 855 @retval EFI_SUCCESS The Unicode string for the Driver specified by 856 This and the language specified by Language was 857 returned in DriverName. 858 859 @retval EFI_INVALID_PARAMETER Language is NULL. 860 861 @retval EFI_INVALID_PARAMETER DriverName is NULL. 862 863 @retval EFI_UNSUPPORTED The driver specified by This does not support 864 the language specified by Language. 865 866 **/ 867 EFI_STATUS 868 EFIAPI 869 I2cHostComponentNameGetDriverName ( 870 IN EFI_COMPONENT_NAME2_PROTOCOL *This, 871 IN CHAR8 *Language, 872 OUT CHAR16 **DriverName 873 ); 874 875 /** 876 Retrieves a Unicode string that is the user readable name of the controller 877 that is being managed by a driver. 878 879 This function retrieves the user readable name of the controller specified by 880 ControllerHandle and ChildHandle in the form of a Unicode string. If the 881 driver specified by This has a user readable name in the language specified by 882 Language, then a pointer to the controller name is returned in ControllerName, 883 and EFI_SUCCESS is returned. If the driver specified by This is not currently 884 managing the controller specified by ControllerHandle and ChildHandle, 885 then EFI_UNSUPPORTED is returned. If the driver specified by This does not 886 support the language specified by Language, then EFI_UNSUPPORTED is returned. 887 888 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 889 EFI_COMPONENT_NAME_PROTOCOL instance. 890 891 @param ControllerHandle[in] The handle of a controller that the driver 892 specified by This is managing. This handle 893 specifies the controller whose name is to be 894 returned. 895 896 @param ChildHandle[in] The handle of the child controller to retrieve 897 the name of. This is an optional parameter that 898 may be NULL. It will be NULL for device 899 drivers. It will also be NULL for a bus drivers 900 that wish to retrieve the name of the bus 901 controller. It will not be NULL for a bus 902 driver that wishes to retrieve the name of a 903 child controller. 904 905 @param Language[in] A pointer to a Null-terminated ASCII string 906 array indicating the language. This is the 907 language of the driver name that the caller is 908 requesting, and it must match one of the 909 languages specified in SupportedLanguages. The 910 number of languages supported by a driver is up 911 to the driver writer. Language is specified in 912 RFC 4646 or ISO 639-2 language code format. 913 914 @param ControllerName[out] A pointer to the Unicode string to return. 915 This Unicode string is the name of the 916 controller specified by ControllerHandle and 917 ChildHandle in the language specified by 918 Language from the point of view of the driver 919 specified by This. 920 921 @retval EFI_SUCCESS The Unicode string for the user readable name in 922 the language specified by Language for the 923 driver specified by This was returned in 924 DriverName. 925 926 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL. 927 928 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid 929 EFI_HANDLE. 930 931 @retval EFI_INVALID_PARAMETER Language is NULL. 932 933 @retval EFI_INVALID_PARAMETER ControllerName is NULL. 934 935 @retval EFI_UNSUPPORTED The driver specified by This is not currently 936 managing the controller specified by 937 ControllerHandle and ChildHandle. 938 939 @retval EFI_UNSUPPORTED The driver specified by This does not support 940 the language specified by Language. 941 942 **/ 943 EFI_STATUS 944 EFIAPI 945 I2cHostComponentNameGetControllerName ( 946 IN EFI_COMPONENT_NAME2_PROTOCOL *This, 947 IN EFI_HANDLE ControllerHandle, 948 IN EFI_HANDLE ChildHandle OPTIONAL, 949 IN CHAR8 *Language, 950 OUT CHAR16 **ControllerName 951 ); 952 953 /** 954 Handle the bus available event 955 956 This routine is called at TPL_I2C_SYNC. 957 958 @param[in] Event Address of an EFI_EVENT handle 959 @param[in] Context Address of an I2C_HOST_CONTEXT structure 960 961 **/ 962 VOID 963 EFIAPI 964 I2cHostRequestCompleteEvent ( 965 IN EFI_EVENT Event, 966 IN VOID *Context 967 ); 968 969 /** 970 Handle the I2C bus configuration available event 971 972 This routine is called at TPL_I2C_SYNC. 973 974 @param[in] Event Address of an EFI_EVENT handle 975 @param[in] Context Address of an I2C_HOST_CONTEXT structure 976 977 **/ 978 VOID 979 EFIAPI 980 I2cHostI2cBusConfigurationAvailable ( 981 IN EFI_EVENT Event, 982 IN VOID *Context 983 ); 984 985 /** 986 Queue an I2C operation for execution on the I2C controller. 987 988 This routine must be called at or below TPL_NOTIFY. For synchronous 989 requests this routine must be called at or below TPL_CALLBACK. 990 991 N.B. The typical consumers of this API are the I2C bus driver and 992 on rare occasions the I2C test application. Extreme care must be 993 taken by other consumers of this API to prevent confusing the 994 third party I2C drivers due to a state change at the I2C device 995 which the third party I2C drivers did not initiate. I2C platform 996 drivers may use this API within these guidelines. 997 998 This layer uses the concept of I2C bus configurations to describe 999 the I2C bus. An I2C bus configuration is defined as a unique 1000 setting of the multiplexers and switches in the I2C bus which 1001 enable access to one or more I2C devices. When using a switch 1002 to divide a bus, due to speed differences, the I2C platform layer 1003 would define an I2C bus configuration for the I2C devices on each 1004 side of the switch. When using a multiplexer, the I2C platform 1005 layer defines an I2C bus configuration for each of the selector 1006 values required to control the multiplexer. See Figure 1 in the 1007 <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C 1008 Specification</a> for a complex I2C bus configuration. 1009 1010 The I2C host driver processes all operations in FIFO order. Prior to 1011 performing the operation, the I2C host driver calls the I2C platform 1012 driver to reconfigure the switches and multiplexers in the I2C bus 1013 enabling access to the specified I2C device. The I2C platform driver 1014 also selects the maximum bus speed for the device. After the I2C bus 1015 is configured, the I2C host driver calls the I2C port driver to 1016 initialize the I2C controller and start the I2C operation. 1017 1018 @param[in] This Address of an EFI_I2C_HOST_PROTOCOL instance. 1019 @param[in] I2cBusConfiguration I2C bus configuration to access the I2C 1020 device. 1021 @param[in] SlaveAddress Address of the device on the I2C bus. 1022 @param[in] Event Event to set for asynchronous operations, 1023 NULL for synchronous operations 1024 @param[in] RequestPacket Address of an EFI_I2C_REQUEST_PACKET 1025 structure describing the I2C operation 1026 @param[out] I2cStatus Optional buffer to receive the I2C operation 1027 completion status 1028 1029 @retval EFI_SUCCESS The operation completed successfully. 1030 @retval EFI_ABORTED The request did not complete because the driver 1031 was shutdown. 1032 @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large. 1033 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation. 1034 This could indicate the slave device is not present. 1035 @retval EFI_INVALID_PARAMETER RequestPacket is NULL 1036 @retval EFI_INVALID_PARAMETER TPL is too high 1037 @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value 1038 @retval EFI_NO_RESPONSE The I2C device is not responding to the 1039 slave address. EFI_DEVICE_ERROR may also be 1040 returned if the controller can not distinguish 1041 when the NACK occurred. 1042 @retval EFI_NOT_FOUND I2C slave address exceeds maximum address 1043 @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for 1044 the event and then read status pointed to by 1045 the request packet. 1046 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation 1047 @retval EFI_TIMEOUT The transaction did not complete within an internally 1048 specified timeout period. 1049 1050 **/ 1051 EFI_STATUS 1052 EFIAPI 1053 I2cHostQueueRequest ( 1054 IN CONST EFI_I2C_HOST_PROTOCOL *This, 1055 IN UINTN I2cBusConfiguration, 1056 IN UINTN SlaveAddress, 1057 IN EFI_EVENT Event OPTIONAL, 1058 IN EFI_I2C_REQUEST_PACKET *RequestPacket, 1059 OUT EFI_STATUS *I2cStatus OPTIONAL 1060 ); 1061 1062 /** 1063 The user Entry Point for I2C host module. The user code starts with this function. 1064 1065 @param[in] ImageHandle The firmware allocated handle for the EFI image. 1066 @param[in] SystemTable A pointer to the EFI System Table. 1067 1068 @retval EFI_SUCCESS The entry point is executed successfully. 1069 @retval other Some error occurs when executing this entry point. 1070 1071 **/ 1072 EFI_STATUS 1073 EFIAPI 1074 InitializeI2cHost( 1075 IN EFI_HANDLE ImageHandle, 1076 IN EFI_SYSTEM_TABLE *SystemTable 1077 ); 1078 1079 /** 1080 This is the unload handle for I2C host module. 1081 1082 Disconnect the driver specified by ImageHandle from all the devices in the handle database. 1083 Uninstall all the protocols installed in the driver entry point. 1084 1085 @param[in] ImageHandle The drivers' driver image. 1086 1087 @retval EFI_SUCCESS The image is unloaded. 1088 @retval Others Failed to unload the image. 1089 1090 **/ 1091 EFI_STATUS 1092 EFIAPI 1093 I2cHostUnload ( 1094 IN EFI_HANDLE ImageHandle 1095 ); 1096 1097 #endif // __I2C_DXE_H__ 1098