MdeModulePkg/Bus/I2c/I2cDxe/I2cHost.c

   1 /** @file
   2   This file implements I2C Host Protocol which provides callers with the ability to
   3   do I/O transactions to all of the devices on the I2C bus.
   4
   5   Copyright (c) 2013 - 2014, Intel Corporation. All rights reserved.<BR>
   6   This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #include "I2cDxe.h"
  17
  18 EFI_DRIVER_BINDING_PROTOCOL gI2cHostDriverBinding = {
  19   I2cHostDriverSupported,
  20   I2cHostDriverStart,
  21   I2cHostDriverStop,
  22   0x10,
  23   NULL,
  24   NULL
  25 };
  26
  27 //
  28 // Driver name table
  29 //
  30 GLOBAL_REMOVE_IF_UNREFERENCED EFI_UNICODE_STRING_TABLE mI2cHostDriverNameTable[] = {
  31   { "eng;en", L"I2c Host Driver" },
  32   { NULL , NULL }
  33 };
  34
  35 //
  36 // EFI Component Name Protocol
  37 //
  38 GLOBAL_REMOVE_IF_UNREFERENCED EFI_COMPONENT_NAME_PROTOCOL  gI2cHostComponentName = {
  39   (EFI_COMPONENT_NAME_GET_DRIVER_NAME) I2cHostComponentNameGetDriverName,
  40   (EFI_COMPONENT_NAME_GET_CONTROLLER_NAME) I2cHostComponentNameGetControllerName,
  41   "eng"
  42 };
  43
  44 //
  45 // EFI Component Name 2 Protocol
  46 //
  47 GLOBAL_REMOVE_IF_UNREFERENCED EFI_COMPONENT_NAME2_PROTOCOL gI2cHostComponentName2 = {
  48   I2cHostComponentNameGetDriverName,
  49   I2cHostComponentNameGetControllerName,
  50   "en"
  51 };
  52
  53 /**
  54   Retrieves a Unicode string that is the user readable name of the driver.
  55
  56   This function retrieves the user readable name of a driver in the form of a
  57   Unicode string. If the driver specified by This has a user readable name in
  58   the language specified by Language, then a pointer to the driver name is
  59   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
  60   by This does not support the language specified by Language,
  61   then EFI_UNSUPPORTED is returned.
  62
  63   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
  64                                 EFI_COMPONENT_NAME_PROTOCOL instance.
  65
  66   @param  Language[in]          A pointer to a Null-terminated ASCII string
  67                                 array indicating the language. This is the
  68                                 language of the driver name that the caller is
  69                                 requesting, and it must match one of the
  70                                 languages specified in SupportedLanguages. The
  71                                 number of languages supported by a driver is up
  72                                 to the driver writer. Language is specified
  73                                 in RFC 4646 or ISO 639-2 language code format.
  74
  75   @param  DriverName[out]       A pointer to the Unicode string to return.
  76                                 This Unicode string is the name of the
  77                                 driver specified by This in the language
  78                                 specified by Language.
  79
  80   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
  81                                 This and the language specified by Language was
  82                                 returned in DriverName.
  83
  84   @retval EFI_INVALID_PARAMETER Language is NULL.
  85
  86   @retval EFI_INVALID_PARAMETER DriverName is NULL.
  87
  88   @retval EFI_UNSUPPORTED       The driver specified by This does not support
  89                                 the language specified by Language.
  90
  91 **/
  92 EFI_STATUS
  93 EFIAPI
  94 I2cHostComponentNameGetDriverName (
  95   IN  EFI_COMPONENT_NAME2_PROTOCOL  *This,
  96   IN  CHAR8                        *Language,
  97   OUT CHAR16                       **DriverName
  98   )
  99 {
 100   return LookupUnicodeString2 (
 101            Language,
 102            This->SupportedLanguages,
 103            mI2cHostDriverNameTable,
 104            DriverName,
 105            (BOOLEAN)(This != &gI2cHostComponentName2)
 106            );
 107 }
 108
 109 /**
 110   Retrieves a Unicode string that is the user readable name of the controller
 111   that is being managed by a driver.
 112
 113   This function retrieves the user readable name of the controller specified by
 114   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 115   driver specified by This has a user readable name in the language specified by
 116   Language, then a pointer to the controller name is returned in ControllerName,
 117   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 118   managing the controller specified by ControllerHandle and ChildHandle,
 119   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 120   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 121
 122   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 123                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 124
 125   @param  ControllerHandle[in]  The handle of a controller that the driver
 126                                 specified by This is managing.  This handle
 127                                 specifies the controller whose name is to be
 128                                 returned.
 129
 130   @param  ChildHandle[in]       The handle of the child controller to retrieve
 131                                 the name of.  This is an optional parameter that
 132                                 may be NULL.  It will be NULL for device
 133                                 drivers.  It will also be NULL for a bus drivers
 134                                 that wish to retrieve the name of the bus
 135                                 controller.  It will not be NULL for a bus
 136                                 driver that wishes to retrieve the name of a
 137                                 child controller.
 138
 139   @param  Language[in]          A pointer to a Null-terminated ASCII string
 140                                 array indicating the language.  This is the
 141                                 language of the driver name that the caller is
 142                                 requesting, and it must match one of the
 143                                 languages specified in SupportedLanguages. The
 144                                 number of languages supported by a driver is up
 145                                 to the driver writer. Language is specified in
 146                                 RFC 4646 or ISO 639-2 language code format.
 147
 148   @param  ControllerName[out]   A pointer to the Unicode string to return.
 149                                 This Unicode string is the name of the
 150                                 controller specified by ControllerHandle and
 151                                 ChildHandle in the language specified by
 152                                 Language from the point of view of the driver
 153                                 specified by This.
 154
 155   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 156                                 the language specified by Language for the
 157                                 driver specified by This was returned in
 158                                 DriverName.
 159
 160   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 161
 162   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 163                                 EFI_HANDLE.
 164
 165   @retval EFI_INVALID_PARAMETER Language is NULL.
 166
 167   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 168
 169   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 170                                 managing the controller specified by
 171                                 ControllerHandle and ChildHandle.
 172
 173   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 174                                 the language specified by Language.
 175
 176 **/
 177 EFI_STATUS
 178 EFIAPI
 179 I2cHostComponentNameGetControllerName (
 180   IN  EFI_COMPONENT_NAME2_PROTOCOL                    *This,
 181   IN  EFI_HANDLE                                      ControllerHandle,
 182   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 183   IN  CHAR8                                           *Language,
 184   OUT CHAR16                                          **ControllerName
 185   )
 186 {
 187   return EFI_UNSUPPORTED;
 188 }
 189
 190 /**
 191   Tests to see if this driver supports a given controller. If a child device is provided,
 192   it further tests to see if this driver supports creating a handle for the specified child device.
 193
 194   This function checks to see if the driver specified by This supports the device specified by
 195   ControllerHandle. Drivers will typically use the device path attached to
 196   ControllerHandle and/or the services from the bus I/O abstraction attached to
 197   ControllerHandle to determine if the driver supports ControllerHandle. This function
 198   may be called many times during platform initialization. In order to reduce boot times, the tests
 199   performed by this function must be very small, and take as little time as possible to execute. This
 200   function must not change the state of any hardware devices, and this function must be aware that the
 201   device specified by ControllerHandle may already be managed by the same driver or a
 202   different driver. This function must match its calls to AllocatePages() with FreePages(),
 203   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 204   Since ControllerHandle may have been previously started by the same driver, if a protocol is
 205   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 206   to guarantee the state of ControllerHandle is not modified by this function.
 207
 208   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 209   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 210                                    must support a protocol interface that supplies
 211                                    an I/O abstraction to the driver.
 212   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 213                                    parameter is ignored by device drivers, and is optional for bus
 214                                    drivers. For bus drivers, if this parameter is not NULL, then
 215                                    the bus driver must determine if the bus controller specified
 216                                    by ControllerHandle and the child controller specified
 217                                    by RemainingDevicePath are both supported by this
 218                                    bus driver.
 219
 220   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 221                                    RemainingDevicePath is supported by the driver specified by This.
 222   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 223                                    RemainingDevicePath is already being managed by the driver
 224                                    specified by This.
 225   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 226                                    RemainingDevicePath is already being managed by a different
 227                                    driver or an application that requires exclusive access.
 228                                    Currently not implemented.
 229   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 230                                    RemainingDevicePath is not supported by the driver specified by This.
 231 **/
 232 EFI_STATUS
 233 EFIAPI
 234 I2cHostDriverSupported (
 235   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 236   IN EFI_HANDLE                   Controller,
 237   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 238   )
 239 {
 240   EFI_I2C_MASTER_PROTOCOL                       *I2cMaster;
 241   EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL *I2cBusConfigurationManagement;
 242   EFI_STATUS                                    Status;
 243
 244   //
 245   //  Locate I2C Bus Configuration Management Protocol
 246   //
 247   Status = gBS->OpenProtocol (
 248                   Controller,
 249                   &gEfiI2cBusConfigurationManagementProtocolGuid,
 250                   (VOID **)&I2cBusConfigurationManagement,
 251                   This->DriverBindingHandle,
 252                   Controller,
 253                   EFI_OPEN_PROTOCOL_BY_DRIVER
 254                   );
 255   if (EFI_ERROR (Status)) {
 256     return Status;
 257   }
 258
 259   //
 260   // Close the protocol because we don't use it here
 261   //
 262   gBS->CloseProtocol (
 263                   Controller,
 264                   &gEfiI2cBusConfigurationManagementProtocolGuid,
 265                   This->DriverBindingHandle,
 266                   Controller
 267                   );
 268
 269   //
 270   //  Locate I2C Master Protocol
 271   //
 272   Status = gBS->OpenProtocol (
 273                   Controller,
 274                   &gEfiI2cMasterProtocolGuid,
 275                   (VOID **)&I2cMaster,
 276                   This->DriverBindingHandle,
 277                   Controller,
 278                   EFI_OPEN_PROTOCOL_GET_PROTOCOL
 279                   );
 280   if (EFI_ERROR (Status)) {
 281     return Status;
 282   }
 283
 284   return EFI_SUCCESS;
 285 }
 286
 287 /**
 288   Starts a device controller or a bus controller.
 289
 290   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 291   As a result, much of the error checking on the parameters to Start() has been moved into this
 292   common boot service. It is legal to call Start() from other locations,
 293   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 294   1. ControllerHandle must be a valid EFI_HANDLE.
 295   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 296      EFI_DEVICE_PATH_PROTOCOL.
 297   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 298      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 299
 300   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 301   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 302                                    must support a protocol interface that supplies
 303                                    an I/O abstraction to the driver.
 304   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 305                                    parameter is ignored by device drivers, and is optional for bus
 306                                    drivers. For a bus driver, if this parameter is NULL, then handles
 307                                    for all the children of Controller are created by this driver.
 308                                    If this parameter is not NULL and the first Device Path Node is
 309                                    not the End of Device Path Node, then only the handle for the
 310                                    child device specified by the first Device Path Node of
 311                                    RemainingDevicePath is created by this driver.
 312                                    If the first Device Path Node of RemainingDevicePath is
 313                                    the End of Device Path Node, no child handle is created by this
 314                                    driver.
 315
 316   @retval EFI_SUCCESS              The device was started.
 317   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 318   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 319   @retval Others                   The driver failded to start the device.
 320
 321 **/
 322 EFI_STATUS
 323 EFIAPI
 324 I2cHostDriverStart (
 325   IN EFI_DRIVER_BINDING_PROTOCOL        *This,
 326   IN EFI_HANDLE                         Controller,
 327   IN EFI_DEVICE_PATH_PROTOCOL           *RemainingDevicePath
 328   )
 329 {
 330   EFI_STATUS                                          Status;
 331   EFI_I2C_MASTER_PROTOCOL                             *I2cMaster;
 332   EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL       *I2cBusConfigurationManagement;
 333   I2C_HOST_CONTEXT                                    *I2cHostContext;
 334
 335   I2cMaster                     = NULL;
 336   I2cHostContext                = NULL;
 337   I2cBusConfigurationManagement = NULL;
 338
 339   //
 340   // Locate I2C Bus Configuration Management Protocol
 341   //
 342   Status = gBS->OpenProtocol (
 343                   Controller,
 344                   &gEfiI2cBusConfigurationManagementProtocolGuid,
 345                   (VOID **)&I2cBusConfigurationManagement,
 346                   This->DriverBindingHandle,
 347                   Controller,
 348                   EFI_OPEN_PROTOCOL_BY_DRIVER
 349                   );
 350   if (EFI_ERROR (Status)) {
 351     DEBUG ((EFI_D_ERROR, "I2cHost: Open I2C bus configuration error, Status = %r\n", Status));
 352     return Status;
 353   }
 354
 355   //
 356   // Locate I2C Master Protocol
 357   //
 358   Status = gBS->OpenProtocol (
 359                   Controller,
 360                   &gEfiI2cMasterProtocolGuid,
 361                   (VOID **)&I2cMaster,
 362                   This->DriverBindingHandle,
 363                   Controller,
 364                   EFI_OPEN_PROTOCOL_GET_PROTOCOL
 365                   );
 366   if (EFI_ERROR (Status)) {
 367     DEBUG ((EFI_D_ERROR, "I2cHost: Open I2C master error, Status = %r\n", Status));
 368     goto Exit;
 369   }
 370
 371   //
 372   // Allocate the I2C Host Context structure
 373   //
 374   I2cHostContext = AllocateZeroPool (sizeof (I2C_HOST_CONTEXT));
 375   if (I2cHostContext == NULL) {
 376     DEBUG ((EFI_D_ERROR, "I2cHost: there is no enough memory to allocate.\n"));
 377     Status = EFI_OUT_OF_RESOURCES;
 378     goto Exit;
 379   }
 380
 381   //
 382   // Initialize the context structure for the current I2C Controller
 383   //
 384   I2cHostContext->Signature                     = I2C_HOST_SIGNATURE;
 385   I2cHostContext->I2cMaster                     = I2cMaster;
 386   I2cHostContext->I2cBusConfigurationManagement = I2cBusConfigurationManagement;
 387   I2cHostContext->I2cBusConfiguration           = (UINTN) -1;
 388   InitializeListHead(&I2cHostContext->RequestList);
 389
 390   //
 391   // Reset the controller
 392   //
 393   Status = I2cMaster->Reset (I2cMaster);
 394   if (EFI_ERROR (Status)) {
 395     DEBUG ((EFI_D_ERROR, "I2cHost: I2C controller reset failed!\n"));
 396     goto Exit;
 397   }
 398
 399   //
 400   // Create the I2C transaction complete event
 401   //
 402   Status = gBS->CreateEvent (
 403                   EVT_NOTIFY_SIGNAL,
 404                   TPL_I2C_SYNC,
 405                   I2cHostRequestCompleteEvent,
 406                   I2cHostContext,
 407                   &I2cHostContext->I2cEvent
 408                   );
 409   if (EFI_ERROR (Status)) {
 410     DEBUG ((EFI_D_ERROR, "I2cHost: create complete event error, Status = %r\n", Status));
 411     goto Exit;
 412   }
 413
 414   //
 415   // Get the bus management event
 416   //
 417   Status = gBS->CreateEvent (
 418                   EVT_NOTIFY_SIGNAL,
 419                   TPL_I2C_SYNC,
 420                   I2cHostI2cBusConfigurationAvailable,
 421                   I2cHostContext,
 422                   &I2cHostContext->I2cBusConfigurationEvent
 423                   );
 424   if (EFI_ERROR (Status)) {
 425     DEBUG ((EFI_D_ERROR, "I2cHost: create bus available event error, Status = %r\n", Status));
 426     goto Exit;
 427   }
 428
 429   //
 430   // Build the I2C host protocol for the current I2C controller
 431   //
 432   I2cHostContext->I2cHost.QueueRequest              = I2cHostQueueRequest;
 433   I2cHostContext->I2cHost.I2cControllerCapabilities = I2cMaster->I2cControllerCapabilities;
 434
 435   //
 436   //  Install the driver protocol
 437   //
 438   Status = gBS->InstallMultipleProtocolInterfaces (
 439                   &Controller,
 440                   &gEfiI2cHostProtocolGuid,
 441                   &I2cHostContext->I2cHost,
 442                   NULL
 443                   );
 444 Exit:
 445   if (EFI_ERROR (Status)) {
 446     DEBUG ((EFI_D_ERROR, "I2cHost: Start() function failed, Status = %r\n", Status));
 447     if (I2cBusConfigurationManagement != NULL) {
 448       gBS->CloseProtocol (
 449                       Controller,
 450                       &gEfiI2cBusConfigurationManagementProtocolGuid,
 451                       This->DriverBindingHandle,
 452                       Controller
 453                       );
 454     }
 455
 456     if ((I2cHostContext != NULL) && (I2cHostContext->I2cEvent != NULL)) {
 457       gBS->CloseEvent (I2cHostContext->I2cEvent);
 458       I2cHostContext->I2cEvent = NULL;
 459     }
 460
 461     if ((I2cHostContext != NULL) && (I2cHostContext->I2cBusConfigurationEvent != NULL)) {
 462       gBS->CloseEvent (I2cHostContext->I2cBusConfigurationEvent);
 463       I2cHostContext->I2cBusConfigurationEvent = NULL;
 464     }
 465
 466     //
 467     //  Release the context structure upon failure
 468     //
 469     if (I2cHostContext != NULL) {
 470       FreePool (I2cHostContext);
 471     }
 472   }
 473
 474   //
 475   //  Return the operation status.
 476   //
 477   return Status;
 478 }
 479
 480 /**
 481   Stops a device controller or a bus controller.
 482
 483   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 484   As a result, much of the error checking on the parameters to Stop() has been moved
 485   into this common boot service. It is legal to call Stop() from other locations,
 486   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 487   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 488      same driver's Start() function.
 489   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 490      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 491      Start() function, and the Start() function must have called OpenProtocol() on
 492      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 493
 494   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 495   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 496                                 support a bus specific I/O protocol for the driver
 497                                 to use to stop the device.
 498   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 499   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 500                                 if NumberOfChildren is 0.
 501
 502   @retval EFI_SUCCESS           The device was stopped.
 503   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 504
 505 **/
 506 EFI_STATUS
 507 EFIAPI
 508 I2cHostDriverStop (
 509   IN  EFI_DRIVER_BINDING_PROTOCOL       *This,
 510   IN  EFI_HANDLE                        Controller,
 511   IN  UINTN                             NumberOfChildren,
 512   IN  EFI_HANDLE                        *ChildHandleBuffer
 513   )
 514 {
 515   EFI_STATUS                  Status;
 516   I2C_HOST_CONTEXT            *I2cHostContext;
 517   EFI_I2C_HOST_PROTOCOL       *I2cHost;
 518   EFI_TPL                     TplPrevious;
 519
 520   TplPrevious = EfiGetCurrentTpl ();
 521   if (TplPrevious > TPL_I2C_SYNC) {
 522     DEBUG ((EFI_D_ERROR, "I2cHost: TPL %d is too high in Stop.\n", TplPrevious));
 523     return EFI_DEVICE_ERROR;
 524   }
 525
 526   Status = gBS->OpenProtocol (
 527                   Controller,
 528                   &gEfiI2cHostProtocolGuid,
 529                   (VOID **) &I2cHost,
 530                   This->DriverBindingHandle,
 531                   Controller,
 532                   EFI_OPEN_PROTOCOL_GET_PROTOCOL
 533                   );
 534
 535   if (EFI_ERROR (Status)) {
 536     return EFI_DEVICE_ERROR;
 537   }
 538
 539   I2cHostContext = I2C_HOST_CONTEXT_FROM_PROTOCOL (I2cHost);
 540
 541   //
 542   // Raise TPL for critical section
 543   //
 544   TplPrevious = gBS->RaiseTPL (TPL_I2C_SYNC);
 545
 546   //
 547   // If there is pending request or pending bus configuration, do not stop
 548   //
 549   Status = EFI_DEVICE_ERROR;
 550   if (( !I2cHostContext->I2cBusConfigurationManagementPending )
 551     && IsListEmpty (&I2cHostContext->RequestList)) {
 552
 553     //
 554     //  Remove the I2C host protocol
 555     //
 556     Status = gBS->UninstallMultipleProtocolInterfaces (
 557                     Controller,
 558                     &gEfiI2cHostProtocolGuid,
 559                     I2cHost,
 560                     NULL
 561                     );
 562   }
 563
 564   //
 565   // Leave critical section
 566   //
 567   gBS->RestoreTPL (TplPrevious);
 568   if (!EFI_ERROR (Status)) {
 569     gBS->CloseProtocol (
 570            Controller,
 571            &gEfiI2cBusConfigurationManagementProtocolGuid,
 572            This->DriverBindingHandle,
 573            Controller
 574            );
 575
 576     //
 577     // Release I2c Host resources
 578     //
 579     if (I2cHostContext->I2cBusConfigurationEvent != NULL) {
 580       gBS->CloseEvent (I2cHostContext->I2cBusConfigurationEvent);
 581       I2cHostContext->I2cBusConfigurationEvent = NULL;
 582     }
 583
 584     if (I2cHostContext->I2cEvent != NULL) {
 585       gBS->CloseEvent (I2cHostContext->I2cEvent);
 586       I2cHostContext->I2cEvent = NULL;
 587     }
 588
 589     FreePool (I2cHostContext);
 590   }
 591
 592   //
 593   //  Return the stop status
 594   //
 595   return Status;
 596 }
 597
 598 /**
 599   Handle the I2C bus configuration available event
 600
 601   This routine is called at TPL_I2C_SYNC.
 602
 603   @param[in] Event    Address of an EFI_EVENT handle
 604   @param[in] Context  Address of an I2C_HOST_CONTEXT structure
 605
 606 **/
 607 VOID
 608 EFIAPI
 609 I2cHostI2cBusConfigurationAvailable (
 610   IN EFI_EVENT Event,
 611   IN VOID *Context
 612   )
 613 {
 614   I2C_HOST_CONTEXT            *I2cHostContext;
 615   EFI_I2C_MASTER_PROTOCOL     *I2cMaster;
 616   I2C_REQUEST                 *I2cRequest;
 617   LIST_ENTRY                  *EntryHeader;
 618   LIST_ENTRY                  *Entry;
 619   EFI_STATUS                  Status;
 620
 621   //
 622   // Mark this I2C bus configuration management operation as complete
 623   //
 624   I2cHostContext = (I2C_HOST_CONTEXT *)Context;
 625   I2cMaster      = I2cHostContext->I2cMaster;
 626   ASSERT (I2cMaster != NULL);
 627   //
 628   // Clear flag to indicate I2C bus configuration is finished
 629   //
 630   I2cHostContext->I2cBusConfigurationManagementPending = FALSE;
 631
 632   //
 633   //  Validate the completion status
 634   //
 635   if (EFI_ERROR (I2cHostContext->Status)) {
 636     //
 637     // Setting I2C bus configuration failed before
 638     //
 639     I2cHostRequestComplete (I2cHostContext, I2cHostContext->Status);
 640
 641     //
 642     // Unknown I2C bus configuration
 643     // Force next operation to enable the I2C bus configuration
 644     //
 645     I2cHostContext->I2cBusConfiguration = (UINTN) -1;
 646
 647     //
 648     // Do not continue current I2C request
 649     //
 650     return;
 651   }
 652
 653   //
 654   // Get the first request in the link with FIFO order
 655   //
 656   EntryHeader = &I2cHostContext->RequestList;
 657   Entry = GetFirstNode (EntryHeader);
 658   I2cRequest = I2C_REQUEST_FROM_ENTRY (Entry);
 659
 660   //
 661   // Update the I2C bus configuration of the current I2C request
 662   //
 663   I2cHostContext->I2cBusConfiguration = I2cRequest->I2cBusConfiguration;
 664
 665   //
 666   // Start an I2C operation on the host, the status is returned by I2cHostContext->Status
 667   //
 668   Status = I2cMaster->StartRequest (
 669                         I2cMaster,
 670                         I2cRequest->SlaveAddress,
 671                         I2cRequest->RequestPacket,
 672                         I2cHostContext->I2cEvent,
 673                         &I2cHostContext->Status
 674                         );
 675 }
 676
 677 /**
 678   Complete the current request
 679
 680   This routine is called at TPL_I2C_SYNC.
 681
 682   @param[in] I2cHostContext  Address of an I2C_HOST_CONTEXT structure.
 683   @param[in] Status          Status of the I2C operation.
 684
 685   @return This routine returns the input status value.
 686
 687 **/
 688 EFI_STATUS
 689 I2cHostRequestComplete (
 690   I2C_HOST_CONTEXT *I2cHostContext,
 691   EFI_STATUS       Status
 692   )
 693 {
 694   I2C_REQUEST *I2cRequest;
 695   LIST_ENTRY  *EntryHeader;
 696   LIST_ENTRY  *Entry;
 697
 698   //
 699   // Remove the current I2C request from the list
 700   //
 701   EntryHeader = &I2cHostContext->RequestList;
 702   Entry = GetFirstNode (EntryHeader);
 703   I2cRequest = I2C_REQUEST_FROM_ENTRY (Entry);
 704
 705   //
 706   // Save the status for QueueRequest
 707   //
 708   if ( NULL != I2cRequest->Status ) {
 709     *I2cRequest->Status = Status;
 710   }
 711
 712   //
 713   //  Notify the user of the I2C request completion
 714   //
 715   if ( NULL != I2cRequest->Event ) {
 716     gBS->SignalEvent (I2cRequest->Event);
 717   }
 718
 719   //
 720   // Done with this request, remove the current request from list
 721   //
 722   RemoveEntryList (&I2cRequest->Link);
 723   FreePool (I2cRequest->RequestPacket);
 724   FreePool (I2cRequest);
 725
 726   //
 727   // If there is more I2C request, start next one
 728   //
 729   if(!IsListEmpty (EntryHeader)) {
 730     I2cHostRequestEnable (I2cHostContext);
 731   }
 732
 733   return Status;
 734 }
 735
 736 /**
 737   Handle the bus available event
 738
 739   This routine is called at TPL_I2C_SYNC.
 740
 741   @param[in] Event    Address of an EFI_EVENT handle
 742   @param[in] Context  Address of an I2C_HOST_CONTEXT structure
 743
 744 **/
 745 VOID
 746 EFIAPI
 747 I2cHostRequestCompleteEvent (
 748   IN EFI_EVENT Event,
 749   IN VOID *Context
 750   )
 751 {
 752   I2C_HOST_CONTEXT *I2cHostContext;
 753
 754   //
 755   // Handle the completion event
 756   //
 757   I2cHostContext = (I2C_HOST_CONTEXT *)Context;
 758   I2cHostRequestComplete (I2cHostContext, I2cHostContext->Status);
 759 }
 760
 761 /**
 762   Enable access to the I2C bus configuration
 763
 764   @param[in] I2cHostContext     Address of an I2C_HOST_CONTEXT structure
 765
 766   @retval EFI_SUCCESS           The operation completed successfully.
 767   @retval EFI_ABORTED           The request did not complete because the driver
 768                                 was shutdown.
 769   @retval EFI_BAD_BUFFER_SIZE   The WriteBytes or ReadBytes buffer size is too large.
 770   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the operation.
 771                                 This could indicate the slave device is not present.
 772   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
 773   @retval EFI_NO_MAPPING        Invalid I2cBusConfiguration value
 774   @retval EFI_NO_RESPONSE       The I2C device is not responding to the
 775                                 slave address.  EFI_DEVICE_ERROR may also be
 776                                 returned if the controller can not distinguish
 777                                 when the NACK occurred.
 778   @retval EFI_NOT_FOUND         I2C slave address exceeds maximum address
 779   @retval EFI_NOT_READY         I2C bus is busy or operation pending, wait for
 780                                 the event and then read status.
 781   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C operation
 782   @retval EFI_TIMEOUT           The transaction did not complete within an internally
 783                                 specified timeout period.
 784
 785 **/
 786 EFI_STATUS
 787 I2cHostRequestEnable (
 788   I2C_HOST_CONTEXT *I2cHostContext
 789   )
 790 {
 791   UINTN                                                 I2cBusConfiguration;
 792   CONST EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL   *I2cBusConfigurationManagement;
 793   I2C_REQUEST                                           *I2cRequest;
 794   EFI_STATUS                                            Status;
 795   EFI_TPL                                               TplPrevious;
 796   LIST_ENTRY                                            *EntryHeader;
 797   LIST_ENTRY                                            *Entry;
 798
 799   //
 800   //  Assume pending request
 801   //
 802   Status = EFI_NOT_READY;
 803
 804   I2cBusConfigurationManagement = I2cHostContext->I2cBusConfigurationManagement;
 805
 806   //
 807   //  Validate the I2c bus configuration
 808   //
 809   EntryHeader = &I2cHostContext->RequestList;
 810   Entry       = GetFirstNode (EntryHeader);
 811   I2cRequest = I2C_REQUEST_FROM_ENTRY (Entry);
 812
 813   I2cBusConfiguration = I2cRequest->I2cBusConfiguration;
 814
 815   if (I2cHostContext->I2cBusConfiguration != I2cBusConfiguration ) {
 816     //
 817     // Set flag to indicate I2C bus configuration is in progress
 818     //
 819     I2cHostContext->I2cBusConfigurationManagementPending = TRUE;
 820     //
 821     //  Update bus configuration for this device's requesting bus configuration
 822     //
 823     Status = I2cBusConfigurationManagement->EnableI2cBusConfiguration (
 824                 I2cBusConfigurationManagement,
 825                 I2cBusConfiguration,
 826                 I2cHostContext->I2cBusConfigurationEvent,
 827                 &I2cHostContext->Status
 828                 );
 829   } else {
 830     //
 831     //  I2C bus configuration is same, no need change configuration and start I2c transaction directly
 832     //
 833     TplPrevious = gBS->RaiseTPL ( TPL_I2C_SYNC );
 834
 835     //
 836     //  Same I2C bus configuration
 837     //
 838     I2cHostContext->Status = EFI_SUCCESS;
 839     I2cHostI2cBusConfigurationAvailable (I2cHostContext->I2cBusConfigurationEvent, I2cHostContext);
 840
 841     //
 842     //  Release the thread synchronization
 843     //
 844     gBS->RestoreTPL ( TplPrevious );
 845   }
 846   return Status;
 847 }
 848
 849 /**
 850   Queue an I2C operation for execution on the I2C controller.
 851
 852   This routine must be called at or below TPL_NOTIFY.  For synchronous
 853   requests this routine must be called at or below TPL_CALLBACK.
 854
 855   N.B. The typical consumers of this API are the I2C bus driver and
 856   on rare occasions the I2C test application.  Extreme care must be
 857   taken by other consumers of this API to prevent confusing the
 858   third party I2C drivers due to a state change at the I2C device
 859   which the third party I2C drivers did not initiate.  I2C platform
 860   drivers may use this API within these guidelines.
 861
 862   This layer uses the concept of I2C bus configurations to describe
 863   the I2C bus.  An I2C bus configuration is defined as a unique
 864   setting of the multiplexers and switches in the I2C bus which
 865   enable access to one or more I2C devices.  When using a switch
 866   to divide a bus, due to speed differences, the I2C platform layer
 867   would define an I2C bus configuration for the I2C devices on each
 868   side of the switch.  When using a multiplexer, the I2C platform
 869   layer defines an I2C bus configuration for each of the selector
 870   values required to control the multiplexer.  See Figure 1 in the
 871   <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C
 872   Specification</a> for a complex I2C bus configuration.
 873
 874   The I2C host driver processes all operations in FIFO order.  Prior to
 875   performing the operation, the I2C host driver calls the I2C platform
 876   driver to reconfigure the switches and multiplexers in the I2C bus
 877   enabling access to the specified I2C device.  The I2C platform driver
 878   also selects the maximum bus speed for the device.  After the I2C bus
 879   is configured, the I2C host driver calls the I2C port driver to
 880   initialize the I2C controller and start the I2C operation.
 881
 882   @param[in] This             Address of an EFI_I2C_HOST_PROTOCOL instance.
 883   @param[in] I2cBusConfiguration  I2C bus configuration to access the I2C
 884                                   device.
 885   @param[in] SlaveAddress     Address of the device on the I2C bus.
 886   @param[in] Event            Event to set for asynchronous operations,
 887                               NULL for synchronous operations
 888   @param[in] RequestPacket    Address of an EFI_I2C_REQUEST_PACKET
 889                               structure describing the I2C operation
 890   @param[out] I2cStatus       Optional buffer to receive the I2C operation
 891                               completion status
 892
 893   @retval EFI_SUCCESS           The operation completed successfully.
 894   @retval EFI_ABORTED           The request did not complete because the driver
 895                                 was shutdown.
 896   @retval EFI_BAD_BUFFER_SIZE   The WriteBytes or ReadBytes buffer size is too large.
 897   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the operation.
 898                                 This could indicate the slave device is not present.
 899   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
 900   @retval EFI_INVALID_PARAMETER TPL is too high
 901   @retval EFI_NO_MAPPING        Invalid I2cBusConfiguration value
 902   @retval EFI_NO_RESPONSE       The I2C device is not responding to the
 903                                 slave address.  EFI_DEVICE_ERROR may also be
 904                                 returned if the controller can not distinguish
 905                                 when the NACK occurred.
 906   @retval EFI_NOT_FOUND         I2C slave address exceeds maximum address
 907   @retval EFI_NOT_READY         I2C bus is busy or operation pending, wait for
 908                                 the event and then read status pointed to by
 909                                 the request packet.
 910   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C operation
 911   @retval EFI_TIMEOUT           The transaction did not complete within an internally
 912                                 specified timeout period.
 913
 914 **/
 915 EFI_STATUS
 916 EFIAPI
 917 I2cHostQueueRequest (
 918   IN CONST EFI_I2C_HOST_PROTOCOL  *This,
 919   IN UINTN                        I2cBusConfiguration,
 920   IN UINTN                        SlaveAddress,
 921   IN EFI_EVENT                    Event            OPTIONAL,
 922   IN EFI_I2C_REQUEST_PACKET       *RequestPacket,
 923   OUT EFI_STATUS                  *I2cStatus       OPTIONAL
 924   )
 925 {
 926   EFI_STATUS        Status;
 927   EFI_EVENT         SyncEvent;
 928   EFI_TPL           TplPrevious;
 929   I2C_REQUEST       *I2cRequest;
 930   I2C_HOST_CONTEXT  *I2cHostContext;
 931   BOOLEAN           FirstRequest;
 932   UINTN             RequestPacketSize;
 933   UINTN             StartBit;
 934
 935   SyncEvent    = NULL;
 936   FirstRequest = FALSE;
 937   Status       = EFI_SUCCESS;
 938
 939   if (RequestPacket == NULL) {
 940     return EFI_INVALID_PARAMETER;
 941   }
 942
 943   if ((SlaveAddress & I2C_ADDRESSING_10_BIT) != 0) {
 944     //
 945     // 10-bit address, bits 0-9 are used for 10-bit I2C slave addresses,
 946     // bits 10-30 are reserved bits and must be zero
 947     //
 948     StartBit = 10;
 949   } else {
 950     //
 951     // 7-bit address, Bits 0-6 are used for 7-bit I2C slave addresses,
 952     // bits 7-30 are reserved bits and must be zero
 953     //
 954     StartBit = 7;
 955   }
 956
 957   if (BitFieldRead32 ((UINT32)SlaveAddress, StartBit, 30) != 0) {
 958     //
 959     // Reserved bit set in the SlaveAddress parameter
 960     //
 961     return EFI_NOT_FOUND;
 962   }
 963
 964   I2cHostContext = I2C_HOST_CONTEXT_FROM_PROTOCOL (This);
 965
 966   if (Event == NULL) {
 967     //
 968     // For synchronous transaction, register an event used to wait for finishing synchronous transaction
 969     //
 970     Status = gBS->CreateEvent (
 971                 0,
 972                 TPL_I2C_SYNC,
 973                 NULL,
 974                 NULL,
 975                 &SyncEvent
 976                 );
 977     if (EFI_ERROR (Status)) {
 978       return Status;
 979     }
 980   }
 981
 982   //
 983   // TPL should be at or below TPL_NOTIFY.
 984   // For synchronous requests this routine must be called at or below TPL_CALLBACK.
 985   //
 986   TplPrevious = EfiGetCurrentTpl ();
 987   if ((TplPrevious > TPL_I2C_SYNC) || ((Event == NULL) && (TplPrevious > TPL_CALLBACK))) {
 988     DEBUG ((EFI_D_ERROR, "ERROR - TPL %d is too high!\n", TplPrevious));
 989     return EFI_INVALID_PARAMETER;
 990   }
 991
 992   //
 993   // Allocate the request structure
 994   //
 995   I2cRequest = AllocateZeroPool (sizeof (I2C_REQUEST));
 996   if (I2cRequest == NULL) {
 997     DEBUG ((EFI_D_ERROR, "WARNING - Failed to allocate I2C_REQUEST!\n"));
 998     return EFI_OUT_OF_RESOURCES;
 999   }
1000
1001   //
1002   // Initialize the request
1003   //
1004   I2cRequest->Signature           = I2C_REQUEST_SIGNATURE;
1005   I2cRequest->I2cBusConfiguration = I2cBusConfiguration;
1006   I2cRequest->SlaveAddress        = SlaveAddress;
1007   I2cRequest->Event               = (Event == NULL) ? SyncEvent : Event;
1008   I2cRequest->Status              = I2cStatus;
1009
1010   //
1011   // Copy request packet into private buffer, as RequestPacket may be freed during asynchronous transaction
1012   //
1013   RequestPacketSize = sizeof (UINTN) + RequestPacket->OperationCount * sizeof (EFI_I2C_OPERATION);
1014   I2cRequest->RequestPacket = AllocateZeroPool (RequestPacketSize);
1015   CopyMem (I2cRequest->RequestPacket, RequestPacket, RequestPacketSize);
1016
1017   //
1018   // Synchronize with the other threads
1019   //
1020   gBS->RaiseTPL ( TPL_I2C_SYNC );
1021
1022   FirstRequest = IsListEmpty (&I2cHostContext->RequestList);
1023
1024   //
1025   // Insert new I2C request in the list
1026   //
1027   InsertTailList (&I2cHostContext->RequestList, &I2cRequest->Link);
1028
1029   //
1030   // Release the thread synchronization
1031   //
1032   gBS->RestoreTPL (TplPrevious);
1033
1034   if (FirstRequest) {
1035     //
1036     // Start the first I2C request, then the subsequent of I2C request will continue
1037     //
1038     Status = I2cHostRequestEnable (I2cHostContext);
1039   }
1040
1041   if (Event != NULL) {
1042     //
1043     // For asynchronous, return EFI_SUCCESS indicating that the asynchronously I2C transaction was queued.
1044     // No real I2C operation status in I2cStatus
1045     //
1046     return EFI_SUCCESS;
1047   }
1048
1049   //
1050   // For synchronous transaction, wait for the operation completion
1051   //
1052   do {
1053     Status = gBS->CheckEvent (SyncEvent);
1054   } while (Status == EFI_NOT_READY);
1055
1056   //
1057   // Get the I2C operation status
1058   //
1059   Status = I2cHostContext->Status;
1060
1061   //
1062   // Return the I2C operation status
1063   //
1064   if (I2cStatus != NULL) {
1065     *I2cStatus = Status;
1066   }
1067
1068   //
1069   // Close the event if necessary
1070   //
1071   if (SyncEvent != NULL) {
1072     gBS->CloseEvent (SyncEvent);
1073   }
1074
1075   return Status;
1076 }
1077
1078 /**
1079   The user Entry Point for I2C host module. The user code starts with this function.
1080
1081   @param[in] ImageHandle    The firmware allocated handle for the EFI image.
1082   @param[in] SystemTable    A pointer to the EFI System Table.
1083
1084   @retval EFI_SUCCESS       The entry point is executed successfully.
1085   @retval other             Some error occurs when executing this entry point.
1086
1087 **/
1088 EFI_STATUS
1089 EFIAPI
1090 InitializeI2cHost(
1091   IN EFI_HANDLE           ImageHandle,
1092   IN EFI_SYSTEM_TABLE     *SystemTable
1093   )
1094 {
1095   EFI_STATUS              Status;
1096
1097   //
1098   // Install driver model protocol(s).
1099   //
1100   Status = EfiLibInstallDriverBindingComponentName2 (
1101              ImageHandle,
1102              SystemTable,
1103              &gI2cHostDriverBinding,
1104              ImageHandle,
1105              &gI2cHostComponentName,
1106              &gI2cHostComponentName2
1107              );
1108   ASSERT_EFI_ERROR (Status);
1109   return Status;
1110 }
1111
1112 /**
1113   This is the unload handle for I2C host module.
1114
1115   Disconnect the driver specified by ImageHandle from all the devices in the handle database.
1116   Uninstall all the protocols installed in the driver entry point.
1117
1118   @param[in] ImageHandle           The drivers' driver image.
1119
1120   @retval    EFI_SUCCESS           The image is unloaded.
1121   @retval    Others                Failed to unload the image.
1122
1123 **/
1124 EFI_STATUS
1125 EFIAPI
1126 I2cHostUnload (
1127   IN EFI_HANDLE             ImageHandle
1128   )
1129 {
1130   EFI_STATUS                        Status;
1131   EFI_HANDLE                        *DeviceHandleBuffer;
1132   UINTN                             DeviceHandleCount;
1133   UINTN                             Index;
1134   EFI_COMPONENT_NAME_PROTOCOL       *ComponentName;
1135   EFI_COMPONENT_NAME2_PROTOCOL      *ComponentName2;
1136
1137   //
1138   // Get the list of all I2C Controller handles in the handle database.
1139   // If there is an error getting the list, then the unload
1140   // operation fails.
1141   //
1142   Status = gBS->LocateHandleBuffer (
1143                   ByProtocol,
1144                   &gEfiI2cHostProtocolGuid,
1145                   NULL,
1146                   &DeviceHandleCount,
1147                   &DeviceHandleBuffer
1148                   );
1149
1150   if (!EFI_ERROR (Status)) {
1151     //
1152     // Disconnect the driver specified by ImageHandle from all
1153     // the devices in the handle database.
1154     //
1155     for (Index = 0; Index < DeviceHandleCount; Index++) {
1156       Status = gBS->DisconnectController (
1157                       DeviceHandleBuffer[Index],
1158                       ImageHandle,
1159                       NULL
1160                       );
1161       if (EFI_ERROR (Status)) {
1162         goto Done;
1163       }
1164     }
1165   }
1166
1167   //
1168   // Uninstall all the protocols installed in the driver entry point
1169   //
1170   Status = gBS->UninstallMultipleProtocolInterfaces (
1171                   gI2cHostDriverBinding.DriverBindingHandle,
1172                   &gEfiDriverBindingProtocolGuid,
1173                   &gI2cHostDriverBinding,
1174                   NULL
1175                   );
1176   ASSERT_EFI_ERROR (Status);
1177
1178   //
1179   // Note we have to one by one uninstall the following protocols.
1180   // It's because some of them are optionally installed based on
1181   // the following PCD settings.
1182   //   gEfiMdePkgTokenSpaceGuid.PcdDriverDiagnosticsDisable
1183   //   gEfiMdePkgTokenSpaceGuid.PcdComponentNameDisable
1184   //   gEfiMdePkgTokenSpaceGuid.PcdDriverDiagnostics2Disable
1185   //   gEfiMdePkgTokenSpaceGuid.PcdComponentName2Disable
1186   //
1187   Status = gBS->HandleProtocol (
1188                   gI2cHostDriverBinding.DriverBindingHandle,
1189                   &gEfiComponentNameProtocolGuid,
1190                   (VOID **) &ComponentName
1191                   );
1192   if (!EFI_ERROR (Status)) {
1193     gBS->UninstallProtocolInterface (
1194            gI2cHostDriverBinding.DriverBindingHandle,
1195            &gEfiComponentNameProtocolGuid,
1196            ComponentName
1197            );
1198   }
1199
1200   Status = gBS->HandleProtocol (
1201                   gI2cHostDriverBinding.DriverBindingHandle,
1202                   &gEfiComponentName2ProtocolGuid,
1203                   (VOID **) &ComponentName2
1204                   );
1205   if (!EFI_ERROR (Status)) {
1206     gBS->UninstallProtocolInterface (
1207            gI2cHostDriverBinding.DriverBindingHandle,
1208            &gEfiComponentName2ProtocolGuid,
1209            ComponentName2
1210            );
1211   }
1212
1213   Status = EFI_SUCCESS;
1214
1215 Done:
1216   //
1217   // Free the buffer containing the list of handles from the handle database
1218   //
1219   if (DeviceHandleBuffer != NULL) {
1220     gBS->FreePool (DeviceHandleBuffer);
1221   }
1222
1223   return Status;
1224 }