MdeModulePkg/Bus/I2c/I2cDxe/I2cBus.c

   1 /** @file
   2   This file implements I2C IO Protocol which enables the user to manipulate a single
   3   I2C device independent of the host controller and I2C design.
   4
   5   Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #include "I2cDxe.h"
  11
  12 //
  13 //  EFI_DRIVER_BINDING_PROTOCOL instance
  14 //
  15 EFI_DRIVER_BINDING_PROTOCOL gI2cBusDriverBinding = {
  16   I2cBusDriverSupported,
  17   I2cBusDriverStart,
  18   I2cBusDriverStop,
  19   0x10,
  20   NULL,
  21   NULL
  22 };
  23
  24 //
  25 // Template for I2C Bus Child Device.
  26 //
  27 I2C_DEVICE_CONTEXT gI2cDeviceContextTemplate = {
  28   I2C_DEVICE_SIGNATURE,
  29   NULL,
  30   {                     // I2cIo Protocol
  31     I2cBusQueueRequest, // QueueRequest
  32     NULL,               // DeviceGuid
  33     0,                  // DeviceIndex
  34     0,                  // HardwareRevision
  35     NULL                // I2cControllerCapabilities
  36   },
  37   NULL,                 // DevicePath
  38   NULL,                 // I2cDevice
  39   NULL,                 // I2cBusContext
  40 };
  41
  42 //
  43 // Template for controller device path node.
  44 //
  45 CONTROLLER_DEVICE_PATH gControllerDevicePathTemplate = {
  46   {
  47     HARDWARE_DEVICE_PATH,
  48     HW_CONTROLLER_DP,
  49     {
  50       (UINT8) (sizeof (CONTROLLER_DEVICE_PATH)),
  51       (UINT8) ((sizeof (CONTROLLER_DEVICE_PATH)) >> 8)
  52     }
  53   },
  54   0
  55 };
  56
  57 //
  58 // Template for vendor device path node.
  59 //
  60 VENDOR_DEVICE_PATH gVendorDevicePathTemplate = {
  61   {
  62     HARDWARE_DEVICE_PATH,
  63     HW_VENDOR_DP,
  64     {
  65       (UINT8) (sizeof (VENDOR_DEVICE_PATH)),
  66       (UINT8) ((sizeof (VENDOR_DEVICE_PATH)) >> 8)
  67     }
  68   },
  69   { 0x0, 0x0, 0x0, { 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0 }}
  70 };
  71
  72 //
  73 // Driver name table
  74 //
  75 GLOBAL_REMOVE_IF_UNREFERENCED EFI_UNICODE_STRING_TABLE mI2cBusDriverNameTable[] = {
  76   { "eng;en", (CHAR16 *) L"I2C Bus Driver" },
  77   { NULL , NULL }
  78 };
  79
  80 //
  81 // EFI Component Name Protocol
  82 //
  83 GLOBAL_REMOVE_IF_UNREFERENCED EFI_COMPONENT_NAME_PROTOCOL  gI2cBusComponentName = {
  84   (EFI_COMPONENT_NAME_GET_DRIVER_NAME) I2cBusComponentNameGetDriverName,
  85   (EFI_COMPONENT_NAME_GET_CONTROLLER_NAME) I2cBusComponentNameGetControllerName,
  86   "eng"
  87 };
  88
  89 //
  90 // EFI Component Name 2 Protocol
  91 //
  92 GLOBAL_REMOVE_IF_UNREFERENCED EFI_COMPONENT_NAME2_PROTOCOL gI2cBusComponentName2 = {
  93   I2cBusComponentNameGetDriverName,
  94   I2cBusComponentNameGetControllerName,
  95   "en"
  96 };
  97
  98 /**
  99   Retrieves a Unicode string that is the user readable name of the driver.
 100
 101   This function retrieves the user readable name of a driver in the form of a
 102   Unicode string. If the driver specified by This has a user readable name in
 103   the language specified by Language, then a pointer to the driver name is
 104   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 105   by This does not support the language specified by Language,
 106   then EFI_UNSUPPORTED is returned.
 107
 108   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 109                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 110
 111   @param  Language[in]          A pointer to a Null-terminated ASCII string
 112                                 array indicating the language. This is the
 113                                 language of the driver name that the caller is
 114                                 requesting, and it must match one of the
 115                                 languages specified in SupportedLanguages. The
 116                                 number of languages supported by a driver is up
 117                                 to the driver writer. Language is specified
 118                                 in RFC 4646 or ISO 639-2 language code format.
 119
 120   @param  DriverName[out]       A pointer to the Unicode string to return.
 121                                 This Unicode string is the name of the
 122                                 driver specified by This in the language
 123                                 specified by Language.
 124
 125   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 126                                 This and the language specified by Language was
 127                                 returned in DriverName.
 128
 129   @retval EFI_INVALID_PARAMETER Language is NULL.
 130
 131   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 132
 133   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 134                                 the language specified by Language.
 135
 136 **/
 137 EFI_STATUS
 138 EFIAPI
 139 I2cBusComponentNameGetDriverName (
 140   IN  EFI_COMPONENT_NAME2_PROTOCOL  *This,
 141   IN  CHAR8                        *Language,
 142   OUT CHAR16                       **DriverName
 143   )
 144 {
 145   return LookupUnicodeString2 (
 146            Language,
 147            This->SupportedLanguages,
 148            mI2cBusDriverNameTable,
 149            DriverName,
 150            (BOOLEAN)(This != &gI2cBusComponentName2)
 151            );
 152 }
 153
 154 /**
 155   Retrieves a Unicode string that is the user readable name of the controller
 156   that is being managed by a driver.
 157
 158   This function retrieves the user readable name of the controller specified by
 159   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 160   driver specified by This has a user readable name in the language specified by
 161   Language, then a pointer to the controller name is returned in ControllerName,
 162   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 163   managing the controller specified by ControllerHandle and ChildHandle,
 164   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 165   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 166
 167   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 168                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 169
 170   @param  ControllerHandle[in]  The handle of a controller that the driver
 171                                 specified by This is managing.  This handle
 172                                 specifies the controller whose name is to be
 173                                 returned.
 174
 175   @param  ChildHandle[in]       The handle of the child controller to retrieve
 176                                 the name of.  This is an optional parameter that
 177                                 may be NULL.  It will be NULL for device
 178                                 drivers.  It will also be NULL for a bus drivers
 179                                 that wish to retrieve the name of the bus
 180                                 controller.  It will not be NULL for a bus
 181                                 driver that wishes to retrieve the name of a
 182                                 child controller.
 183
 184   @param  Language[in]          A pointer to a Null-terminated ASCII string
 185                                 array indicating the language.  This is the
 186                                 language of the driver name that the caller is
 187                                 requesting, and it must match one of the
 188                                 languages specified in SupportedLanguages. The
 189                                 number of languages supported by a driver is up
 190                                 to the driver writer. Language is specified in
 191                                 RFC 4646 or ISO 639-2 language code format.
 192
 193   @param  ControllerName[out]   A pointer to the Unicode string to return.
 194                                 This Unicode string is the name of the
 195                                 controller specified by ControllerHandle and
 196                                 ChildHandle in the language specified by
 197                                 Language from the point of view of the driver
 198                                 specified by This.
 199
 200   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 201                                 the language specified by Language for the
 202                                 driver specified by This was returned in
 203                                 DriverName.
 204
 205   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 206
 207   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 208                                 EFI_HANDLE.
 209
 210   @retval EFI_INVALID_PARAMETER Language is NULL.
 211
 212   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 213
 214   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 215                                 managing the controller specified by
 216                                 ControllerHandle and ChildHandle.
 217
 218   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 219                                 the language specified by Language.
 220
 221 **/
 222 EFI_STATUS
 223 EFIAPI
 224 I2cBusComponentNameGetControllerName (
 225   IN  EFI_COMPONENT_NAME2_PROTOCOL                     *This,
 226   IN  EFI_HANDLE                                      ControllerHandle,
 227   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 228   IN  CHAR8                                           *Language,
 229   OUT CHAR16                                          **ControllerName
 230   )
 231 {
 232   return EFI_UNSUPPORTED;
 233 }
 234
 235 /**
 236   Check if the child of I2C controller has been created.
 237
 238   @param[in] This                         A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 239   @param[in] Controller                   I2C controller handle.
 240   @param[in] RemainingDevicePath          A pointer to the remaining portion of a device path.
 241   @param[in] RemainingHasControllerNode   Indicate if RemainingDevicePath contains CONTROLLER_DEVICE_PATH.
 242   @param[in] RemainingControllerNumber    Controller number in CONTROLLER_DEVICE_PATH.
 243
 244   @retval EFI_SUCCESS                     The child of I2C controller is not created.
 245   @retval Others                          The child of I2C controller has been created or other errors happen.
 246
 247 **/
 248 EFI_STATUS
 249 CheckRemainingDevicePath (
 250   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 251   IN EFI_HANDLE                   Controller,
 252   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath,
 253   IN BOOLEAN                      RemainingHasControllerNode,
 254   IN UINT32                       RemainingControllerNumber
 255   )
 256 {
 257   EFI_STATUS                              Status;
 258   EFI_DEVICE_PATH_PROTOCOL                *SystemDevicePath;
 259   EFI_OPEN_PROTOCOL_INFORMATION_ENTRY     *OpenInfoBuffer;
 260   UINTN                                   EntryCount;
 261   UINTN                                   Index;
 262   BOOLEAN                                 SystemHasControllerNode;
 263   UINT32                                  SystemControllerNumber;
 264
 265   SystemHasControllerNode = FALSE;
 266   SystemControllerNumber    = 0;
 267
 268   Status = gBS->OpenProtocolInformation (
 269                   Controller,
 270                   &gEfiI2cHostProtocolGuid,
 271                   &OpenInfoBuffer,
 272                   &EntryCount
 273                   );
 274   if (EFI_ERROR (Status)) {
 275     return Status;
 276   }
 277
 278   for (Index = 0; Index < EntryCount; Index++) {
 279     if ((OpenInfoBuffer[Index].Attributes & EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER) != 0) {
 280       Status = gBS->OpenProtocol (
 281                       OpenInfoBuffer[Index].ControllerHandle,
 282                       &gEfiDevicePathProtocolGuid,
 283                       (VOID **) &SystemDevicePath,
 284                       This->DriverBindingHandle,
 285                       Controller,
 286                       EFI_OPEN_PROTOCOL_GET_PROTOCOL
 287                       );
 288       if (!EFI_ERROR (Status)) {
 289         //
 290         // Find vendor device path node and compare
 291         //
 292         while (!IsDevicePathEnd (SystemDevicePath)) {
 293           if ((DevicePathType (SystemDevicePath) == HARDWARE_DEVICE_PATH) &&
 294               (DevicePathSubType (SystemDevicePath) == HW_VENDOR_DP)) {
 295             //
 296             // Check if vendor device path is same between system device path and remaining device path
 297             //
 298             if (CompareMem (SystemDevicePath, RemainingDevicePath, sizeof (VENDOR_DEVICE_PATH)) == 0) {
 299               //
 300               // Get controller node appended after vendor node
 301               //
 302               SystemDevicePath = NextDevicePathNode (SystemDevicePath);
 303               if ((DevicePathType (SystemDevicePath) == HARDWARE_DEVICE_PATH) &&
 304                   (DevicePathSubType (SystemDevicePath) == HW_CONTROLLER_DP)) {
 305                 SystemHasControllerNode = TRUE;
 306                 SystemControllerNumber    = ((CONTROLLER_DEVICE_PATH *) SystemDevicePath)->ControllerNumber;
 307               } else {
 308                 SystemHasControllerNode = FALSE;
 309                 SystemControllerNumber    = 0;
 310               }
 311               if (((SystemHasControllerNode)  && (!RemainingHasControllerNode) && (SystemControllerNumber == 0)) ||
 312                   ((!SystemHasControllerNode) && (RemainingHasControllerNode)  && (RemainingControllerNumber == 0)) ||
 313                   ((SystemHasControllerNode)  && (RemainingHasControllerNode)  && (SystemControllerNumber == RemainingControllerNumber)) ||
 314                   ((!SystemHasControllerNode) && (!RemainingHasControllerNode))) {
 315                   DEBUG ((EFI_D_ERROR, "This I2C device has been already started.\n"));
 316                   Status = EFI_UNSUPPORTED;
 317                   break;
 318               }
 319             }
 320           }
 321           SystemDevicePath = NextDevicePathNode (SystemDevicePath);
 322         }
 323         if (EFI_ERROR (Status)) {
 324           break;
 325         }
 326       }
 327     }
 328   }
 329   FreePool (OpenInfoBuffer);
 330   return Status;
 331 }
 332
 333 /**
 334   Tests to see if this driver supports a given controller. If a child device is provided,
 335   it further tests to see if this driver supports creating a handle for the specified child device.
 336
 337   This function checks to see if the driver specified by This supports the device specified by
 338   ControllerHandle. Drivers will typically use the device path attached to
 339   ControllerHandle and/or the services from the bus I/O abstraction attached to
 340   ControllerHandle to determine if the driver supports ControllerHandle. This function
 341   may be called many times during platform initialization. In order to reduce boot times, the tests
 342   performed by this function must be very small, and take as little time as possible to execute. This
 343   function must not change the state of any hardware devices, and this function must be aware that the
 344   device specified by ControllerHandle may already be managed by the same driver or a
 345   different driver. This function must match its calls to AllocatePages() with FreePages(),
 346   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 347   Since ControllerHandle may have been previously started by the same driver, if a protocol is
 348   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 349   to guarantee the state of ControllerHandle is not modified by this function.
 350
 351   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 352   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 353                                    must support a protocol interface that supplies
 354                                    an I/O abstraction to the driver.
 355   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 356                                    parameter is ignored by device drivers, and is optional for bus
 357                                    drivers. For bus drivers, if this parameter is not NULL, then
 358                                    the bus driver must determine if the bus controller specified
 359                                    by ControllerHandle and the child controller specified
 360                                    by RemainingDevicePath are both supported by this
 361                                    bus driver.
 362
 363   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 364                                    RemainingDevicePath is supported by the driver specified by This.
 365   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 366                                    RemainingDevicePath is already being managed by the driver
 367                                    specified by This.
 368   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 369                                    RemainingDevicePath is already being managed by a different
 370                                    driver or an application that requires exclusive access.
 371                                    Currently not implemented.
 372   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 373                                    RemainingDevicePath is not supported by the driver specified by This.
 374 **/
 375 EFI_STATUS
 376 EFIAPI
 377 I2cBusDriverSupported (
 378   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 379   IN EFI_HANDLE                   Controller,
 380   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 381   )
 382 {
 383   EFI_STATUS                          Status;
 384   EFI_I2C_ENUMERATE_PROTOCOL          *I2cEnumerate;
 385   EFI_I2C_HOST_PROTOCOL               *I2cHost;
 386   EFI_DEVICE_PATH_PROTOCOL            *ParentDevicePath;
 387   EFI_DEVICE_PATH_PROTOCOL            *DevPathNode;
 388   BOOLEAN                             RemainingHasControllerNode;
 389   UINT32                              RemainingControllerNumber;
 390
 391   RemainingHasControllerNode = FALSE;
 392   RemainingControllerNumber    = 0;
 393
 394   //
 395   //  Determine if the I2c Enumerate Protocol is available
 396   //
 397   Status = gBS->OpenProtocol (
 398                   Controller,
 399                   &gEfiI2cEnumerateProtocolGuid,
 400                   (VOID **) &I2cEnumerate,
 401                   This->DriverBindingHandle,
 402                   Controller,
 403                   EFI_OPEN_PROTOCOL_BY_DRIVER
 404                   );
 405   if ((EFI_ERROR (Status)) && (Status != EFI_ALREADY_STARTED)) {
 406     return Status;
 407   }
 408
 409   if (!EFI_ERROR (Status)) {
 410     gBS->CloseProtocol (
 411           Controller,
 412           &gEfiI2cEnumerateProtocolGuid,
 413           This->DriverBindingHandle,
 414           Controller
 415           );
 416   }
 417
 418   Status = gBS->OpenProtocol (
 419                   Controller,
 420                   &gEfiDevicePathProtocolGuid,
 421                   (VOID **) &ParentDevicePath,
 422                   This->DriverBindingHandle,
 423                   Controller,
 424                   EFI_OPEN_PROTOCOL_BY_DRIVER
 425                   );
 426
 427   if ((EFI_ERROR (Status)) && (Status != EFI_ALREADY_STARTED)) {
 428     return Status;
 429   }
 430
 431   if (!EFI_ERROR (Status)) {
 432     gBS->CloseProtocol (
 433           Controller,
 434           &gEfiDevicePathProtocolGuid,
 435           This->DriverBindingHandle,
 436           Controller
 437           );
 438   }
 439
 440   if ((RemainingDevicePath != NULL) && !IsDevicePathEnd (RemainingDevicePath)) {
 441     //
 442     // Check if the first node of RemainingDevicePath is a hardware vendor device path
 443     //
 444     if ((DevicePathType (RemainingDevicePath) != HARDWARE_DEVICE_PATH) ||
 445         (DevicePathSubType (RemainingDevicePath) != HW_VENDOR_DP)) {
 446       return EFI_UNSUPPORTED;
 447     }
 448     //
 449     // Check if the second node of RemainingDevicePath is a controller node
 450     //
 451     DevPathNode = NextDevicePathNode (RemainingDevicePath);
 452     if (!IsDevicePathEnd (DevPathNode)) {
 453       if ((DevicePathType (DevPathNode) != HARDWARE_DEVICE_PATH) ||
 454           (DevicePathSubType (DevPathNode) != HW_CONTROLLER_DP)) {
 455         return EFI_UNSUPPORTED;
 456       } else {
 457         RemainingHasControllerNode = TRUE;
 458         RemainingControllerNumber    = ((CONTROLLER_DEVICE_PATH *) DevPathNode)->ControllerNumber;
 459       }
 460     }
 461   }
 462
 463   //
 464   // Determine if the I2C Host Protocol is available
 465   //
 466   Status = gBS->OpenProtocol (
 467                   Controller,
 468                   &gEfiI2cHostProtocolGuid,
 469                   (VOID **) &I2cHost,
 470                   This->DriverBindingHandle,
 471                   Controller,
 472                   EFI_OPEN_PROTOCOL_BY_DRIVER
 473                   );
 474
 475   if (!EFI_ERROR (Status)) {
 476     gBS->CloseProtocol (
 477           Controller,
 478           &gEfiI2cHostProtocolGuid,
 479           This->DriverBindingHandle,
 480           Controller
 481           );
 482   }
 483
 484
 485   if (Status == EFI_ALREADY_STARTED) {
 486     if ((RemainingDevicePath == NULL) ||
 487         ((RemainingDevicePath != NULL) && IsDevicePathEnd (RemainingDevicePath))) {
 488       //
 489       // If RemainingDevicePath is NULL or is the End of Device Path Node, return EFI_SUCCESS.
 490       //
 491       Status = EFI_SUCCESS;
 492     } else {
 493       //
 494       // Test if the child with the RemainingDevicePath has already been created.
 495       //
 496       Status = CheckRemainingDevicePath (
 497                  This,
 498                  Controller,
 499                  RemainingDevicePath,
 500                  RemainingHasControllerNode,
 501                  RemainingControllerNumber
 502                  );
 503     }
 504   }
 505
 506   return Status;
 507 }
 508
 509 /**
 510   Starts a device controller or a bus controller.
 511
 512   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 513   As a result, much of the error checking on the parameters to Start() has been moved into this
 514   common boot service. It is legal to call Start() from other locations,
 515   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 516   1. ControllerHandle must be a valid EFI_HANDLE.
 517   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 518      EFI_DEVICE_PATH_PROTOCOL.
 519   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 520      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 521
 522   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 523   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 524                                    must support a protocol interface that supplies
 525                                    an I/O abstraction to the driver.
 526   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 527                                    parameter is ignored by device drivers, and is optional for bus
 528                                    drivers. For a bus driver, if this parameter is NULL, then handles
 529                                    for all the children of Controller are created by this driver.
 530                                    If this parameter is not NULL and the first Device Path Node is
 531                                    not the End of Device Path Node, then only the handle for the
 532                                    child device specified by the first Device Path Node of
 533                                    RemainingDevicePath is created by this driver.
 534                                    If the first Device Path Node of RemainingDevicePath is
 535                                    the End of Device Path Node, no child handle is created by this
 536                                    driver.
 537
 538   @retval EFI_SUCCESS              The device was started.
 539   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 540   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 541   @retval Others                   The driver failed to start the device.
 542
 543 **/
 544 EFI_STATUS
 545 EFIAPI
 546 I2cBusDriverStart (
 547   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 548   IN EFI_HANDLE                   Controller,
 549   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 550   )
 551 {
 552   EFI_I2C_ENUMERATE_PROTOCOL *I2cEnumerate;
 553   EFI_I2C_HOST_PROTOCOL      *I2cHost;
 554   I2C_BUS_CONTEXT            *I2cBusContext;
 555   EFI_STATUS                 Status;
 556   EFI_DEVICE_PATH_PROTOCOL   *ParentDevicePath;
 557
 558   I2cBusContext     = NULL;
 559   ParentDevicePath  = NULL;
 560   I2cEnumerate      = NULL;
 561   I2cHost           = NULL;
 562
 563   //
 564   //  Determine if the I2C controller is available
 565   //
 566   Status = gBS->OpenProtocol (
 567                   Controller,
 568                   &gEfiI2cHostProtocolGuid,
 569                   (VOID**)&I2cHost,
 570                   This->DriverBindingHandle,
 571                   Controller,
 572                   EFI_OPEN_PROTOCOL_BY_DRIVER
 573                   );
 574   if (EFI_ERROR (Status) && (Status != EFI_ALREADY_STARTED)) {
 575     DEBUG ((EFI_D_ERROR, "I2cBus: open I2C host error, Status = %r\n", Status));
 576     return Status;
 577   }
 578
 579   if (Status == EFI_ALREADY_STARTED) {
 580     Status = gBS->OpenProtocol (
 581                     Controller,
 582                     &gEfiCallerIdGuid,
 583                     (VOID **) &I2cBusContext,
 584                     This->DriverBindingHandle,
 585                     Controller,
 586                     EFI_OPEN_PROTOCOL_GET_PROTOCOL
 587                     );
 588     if (EFI_ERROR (Status)) {
 589       DEBUG ((EFI_D_ERROR, "I2cBus: open private protocol error, Status = %r.\n", Status));
 590       return Status;
 591     }
 592   }
 593
 594   //
 595   //  Get the I2C bus enumeration API
 596   //
 597   Status = gBS->OpenProtocol (
 598                   Controller,
 599                   &gEfiI2cEnumerateProtocolGuid,
 600                   (VOID**)&I2cEnumerate,
 601                   This->DriverBindingHandle,
 602                   Controller,
 603                   EFI_OPEN_PROTOCOL_BY_DRIVER
 604                   );
 605   if (EFI_ERROR (Status) && (Status != EFI_ALREADY_STARTED)) {
 606     DEBUG ((EFI_D_ERROR, "I2cBus: open I2C enumerate error, Status = %r\n", Status));
 607     goto Error;
 608   }
 609
 610   Status = gBS->OpenProtocol (
 611                    Controller,
 612                    &gEfiDevicePathProtocolGuid,
 613                    (VOID **) &ParentDevicePath,
 614                    This->DriverBindingHandle,
 615                    Controller,
 616                    EFI_OPEN_PROTOCOL_BY_DRIVER
 617                    );
 618   if (EFI_ERROR (Status) && (Status != EFI_ALREADY_STARTED)) {
 619     DEBUG ((EFI_D_ERROR, "I2cBus: open device path error, Status = %r\n", Status));
 620     goto Error;
 621   }
 622
 623   if ((RemainingDevicePath != NULL) && IsDevicePathEnd (RemainingDevicePath)) {
 624     //
 625     // If RemainingDevicePath is the End of Device Path Node,
 626     // don't create any child device and return EFI_SUCCESS
 627     //
 628     return EFI_SUCCESS;
 629   }
 630
 631   //
 632   // Allocate the buffer for I2C_BUS_CONTEXT if it is not allocated before.
 633   //
 634   if (I2cBusContext == NULL) {
 635     //
 636     //  Allocate the I2C context structure for the current I2C controller
 637     //
 638     I2cBusContext = AllocateZeroPool (sizeof (I2C_BUS_CONTEXT));
 639     if (I2cBusContext == NULL) {
 640       DEBUG ((EFI_D_ERROR, "I2cBus: there is no enough memory to allocate.\n"));
 641       Status = EFI_OUT_OF_RESOURCES;
 642       goto Error;
 643     }
 644
 645     /*
 646        +----------------+
 647     .->| I2C_BUS_CONTEXT|<----- This file Protocol (gEfiCallerIdGuid) installed on I2C Controller handle
 648     |  +----------------+
 649     |
 650     |  +----------------------------+
 651     |  | I2C_DEVICE_CONTEXT         |
 652     `--|                            |
 653        |                            |
 654        | I2C IO Protocol Structure  | <----- I2C IO Protocol
 655        |                            |
 656        +----------------------------+
 657
 658     */
 659     I2cBusContext->I2cHost      = I2cHost;
 660     I2cBusContext->I2cEnumerate = I2cEnumerate;
 661     //
 662     // Parent controller used to create children
 663     //
 664     I2cBusContext->Controller   = Controller;
 665     //
 666     // Parent controller device path used to create children device path
 667     //
 668     I2cBusContext->ParentDevicePath = ParentDevicePath;
 669
 670     I2cBusContext->DriverBindingHandle = This->DriverBindingHandle;
 671
 672     Status = gBS->InstallMultipleProtocolInterfaces (
 673                     &Controller,
 674                     &gEfiCallerIdGuid,
 675                     I2cBusContext,
 676                     NULL
 677                     );
 678     if (EFI_ERROR (Status)) {
 679       DEBUG ((EFI_D_ERROR, "I2cBus: install private protocol error, Status = %r.\n", Status));
 680       goto Error;
 681     }
 682   }
 683
 684   //
 685   //  Start the driver
 686   //
 687   Status = RegisterI2cDevice (I2cBusContext, Controller, RemainingDevicePath);
 688
 689   return Status;
 690
 691 Error:
 692   if (EFI_ERROR (Status)) {
 693     DEBUG ((EFI_D_ERROR, "I2cBus: Start() function failed, Status = %r\n", Status));
 694     if (ParentDevicePath != NULL) {
 695       gBS->CloseProtocol (
 696             Controller,
 697             &gEfiDevicePathProtocolGuid,
 698             This->DriverBindingHandle,
 699             Controller
 700             );
 701     }
 702
 703     if (I2cHost != NULL) {
 704       gBS->CloseProtocol (
 705             Controller,
 706             &gEfiI2cHostProtocolGuid,
 707             This->DriverBindingHandle,
 708             Controller
 709             );
 710     }
 711
 712     if (I2cEnumerate != NULL) {
 713       gBS->CloseProtocol (
 714             Controller,
 715             &gEfiI2cEnumerateProtocolGuid,
 716             This->DriverBindingHandle,
 717             Controller
 718             );
 719     }
 720
 721     if (I2cBusContext != NULL) {
 722       Status = gBS->UninstallMultipleProtocolInterfaces (
 723                       Controller,
 724                       gEfiCallerIdGuid,
 725                       I2cBusContext,
 726                       NULL
 727                       );
 728       FreePool (I2cBusContext);
 729     }
 730   }
 731
 732   //
 733   //  Return the operation status.
 734   //
 735   return Status;
 736 }
 737
 738
 739 /**
 740   Stops a device controller or a bus controller.
 741
 742   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 743   As a result, much of the error checking on the parameters to Stop() has been moved
 744   into this common boot service. It is legal to call Stop() from other locations,
 745   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 746   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 747      same driver's Start() function.
 748   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 749      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 750      Start() function, and the Start() function must have called OpenProtocol() on
 751      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 752
 753   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 754   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 755                                 support a bus specific I/O protocol for the driver
 756                                 to use to stop the device.
 757   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 758   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 759                                 if NumberOfChildren is 0.
 760
 761   @retval EFI_SUCCESS           The device was stopped.
 762   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 763
 764 **/
 765 EFI_STATUS
 766 EFIAPI
 767 I2cBusDriverStop (
 768   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,
 769   IN  EFI_HANDLE                   Controller,
 770   IN  UINTN                        NumberOfChildren,
 771   IN  EFI_HANDLE                   *ChildHandleBuffer
 772   )
 773 {
 774   I2C_BUS_CONTEXT             *I2cBusContext;
 775   EFI_STATUS                  Status;
 776   BOOLEAN                     AllChildrenStopped;
 777   UINTN                       Index;
 778
 779   if (NumberOfChildren == 0) {
 780     gBS->CloseProtocol (
 781           Controller,
 782           &gEfiDevicePathProtocolGuid,
 783           This->DriverBindingHandle,
 784           Controller
 785           );
 786
 787     gBS->CloseProtocol (
 788           Controller,
 789           &gEfiI2cHostProtocolGuid,
 790           This->DriverBindingHandle,
 791           Controller
 792           );
 793
 794     gBS->CloseProtocol (
 795           Controller,
 796           &gEfiI2cEnumerateProtocolGuid,
 797           This->DriverBindingHandle,
 798           Controller
 799           );
 800
 801     Status = gBS->OpenProtocol (
 802                     Controller,
 803                     &gEfiCallerIdGuid,
 804                     (VOID **) &I2cBusContext,
 805                     This->DriverBindingHandle,
 806                     Controller,
 807                     EFI_OPEN_PROTOCOL_GET_PROTOCOL
 808                     );
 809     if (!EFI_ERROR (Status)) {
 810       gBS->UninstallMultipleProtocolInterfaces (
 811             Controller,
 812             &gEfiCallerIdGuid,
 813             I2cBusContext,
 814             NULL
 815             );
 816       //
 817       // No more child now, free bus context data.
 818       //
 819       FreePool (I2cBusContext);
 820     }
 821     return Status;
 822   }
 823
 824   AllChildrenStopped = TRUE;
 825
 826   for (Index = 0; Index < NumberOfChildren; Index++) {
 827
 828     Status = UnRegisterI2cDevice (This, Controller, ChildHandleBuffer[Index]);
 829     if (EFI_ERROR (Status)) {
 830       AllChildrenStopped = FALSE;
 831     }
 832   }
 833
 834   if (!AllChildrenStopped) {
 835     return EFI_DEVICE_ERROR;
 836   }
 837   return EFI_SUCCESS;
 838 }
 839
 840 /**
 841   Enumerate the I2C bus
 842
 843   This routine walks the platform specific data describing the
 844   I2C bus to create the I2C devices where driver GUIDs were
 845   specified.
 846
 847   @param[in] I2cBusContext            Address of an I2C_BUS_CONTEXT structure
 848   @param[in] Controller               Handle to the controller
 849   @param[in] RemainingDevicePath      A pointer to the remaining portion of a device path.
 850
 851   @retval EFI_SUCCESS       The bus is successfully configured
 852
 853 **/
 854 EFI_STATUS
 855 RegisterI2cDevice (
 856   IN I2C_BUS_CONTEXT            *I2cBusContext,
 857   IN EFI_HANDLE                 Controller,
 858   IN EFI_DEVICE_PATH_PROTOCOL   *RemainingDevicePath
 859   )
 860 {
 861   I2C_DEVICE_CONTEXT                *I2cDeviceContext;
 862   EFI_STATUS                        Status;
 863   CONST EFI_I2C_DEVICE              *Device;
 864   CONST EFI_I2C_DEVICE              *TempDevice;
 865   UINT32                            RemainingPathDeviceIndex;
 866   EFI_DEVICE_PATH_PROTOCOL          *DevPathNode;
 867   BOOLEAN                           BuildControllerNode;
 868   UINTN                             Count;
 869
 870   Status                   = EFI_SUCCESS;
 871   BuildControllerNode      = TRUE;
 872
 873   //
 874   // Default DeviceIndex
 875   //
 876   RemainingPathDeviceIndex = 0;
 877
 878   //
 879   // Determine the controller number in Controller Node Device Path when RemainingDevicePath is not NULL.
 880   //
 881   if (RemainingDevicePath != NULL) {
 882     //
 883     // Check if there is a controller node appended after vendor node
 884     //
 885     DevPathNode = NextDevicePathNode (RemainingDevicePath);
 886     if ((DevicePathType (DevPathNode) == HARDWARE_DEVICE_PATH) &&
 887         (DevicePathSubType(DevPathNode) == HW_CONTROLLER_DP)) {
 888       //
 889       // RemainingDevicePath != NULL and RemainingDevicePath contains Controller Node,
 890       // add Controller Node to Device Path on child handle.
 891       //
 892       RemainingPathDeviceIndex = ((CONTROLLER_DEVICE_PATH *) DevPathNode)->ControllerNumber;
 893     } else {
 894       //
 895       // RemainingDevicePath != NULL and RemainingDevicePath does not contain Controller Node,
 896       // do not add controller node to Device Path on child handle.
 897       //
 898       BuildControllerNode = FALSE;
 899     }
 900   }
 901
 902   //
 903   //  Walk the list of I2C devices on this bus
 904   //
 905   Device = NULL;
 906   while (TRUE) {
 907     //
 908     //  Get the next I2C device
 909     //
 910     Status = I2cBusContext->I2cEnumerate->Enumerate (I2cBusContext->I2cEnumerate, &Device);
 911     if (EFI_ERROR (Status) || Device == NULL) {
 912       if (RemainingDevicePath != NULL) {
 913         Status = EFI_NOT_FOUND;
 914       } else {
 915         Status = EFI_SUCCESS;
 916       }
 917       break;
 918     }
 919
 920     //
 921     //  Determine if the device info is valid
 922     //
 923     if ((Device->DeviceGuid == NULL) || (Device->SlaveAddressCount == 0) || (Device->SlaveAddressArray == NULL)) {
 924       DEBUG ((EFI_D_ERROR, "Invalid EFI_I2C_DEVICE reported by I2c Enumerate protocol.\n"));
 925       continue;
 926     }
 927
 928     if (RemainingDevicePath == NULL) {
 929       if (Device->DeviceIndex == 0) {
 930         //
 931         // Determine if the controller node is necessary when controller number is zero in I2C device
 932         //
 933         TempDevice = NULL;
 934         Count      = 0;
 935         while (TRUE) {
 936           //
 937           //  Get the next I2C device
 938           //
 939           Status = I2cBusContext->I2cEnumerate->Enumerate (I2cBusContext->I2cEnumerate, &TempDevice);
 940           if (EFI_ERROR (Status) || TempDevice == NULL) {
 941             Status = EFI_SUCCESS;
 942             break;
 943           }
 944           if (CompareGuid (Device->DeviceGuid, TempDevice->DeviceGuid)) {
 945             Count++;
 946           }
 947         }
 948         if (Count == 1) {
 949           //
 950           // RemainingDevicePath == NULL and only DeviceIndex 0 is present on the I2C bus,
 951           // do not add Controller Node to Device Path on child handle.
 952           //
 953           BuildControllerNode = FALSE;
 954         }
 955       }
 956     } else {
 957       //
 958       // Find I2C device reported in Remaining Device Path
 959       //
 960       if ((!CompareGuid (&((VENDOR_DEVICE_PATH *)RemainingDevicePath)->Guid, Device->DeviceGuid)) ||
 961           (RemainingPathDeviceIndex != Device->DeviceIndex)) {
 962         continue;
 963       }
 964     }
 965
 966     //
 967     // Build the device context for current I2C device.
 968     //
 969     I2cDeviceContext = NULL;
 970     I2cDeviceContext = AllocateCopyPool (sizeof (I2C_DEVICE_CONTEXT), &gI2cDeviceContextTemplate);
 971     ASSERT (I2cDeviceContext != NULL);
 972     if (I2cDeviceContext == NULL) {
 973       continue;
 974     }
 975
 976     //
 977     //  Initialize the specific device context
 978     //
 979     I2cDeviceContext->I2cBusContext          = I2cBusContext;
 980     I2cDeviceContext->I2cDevice              = Device;
 981     I2cDeviceContext->I2cIo.DeviceGuid       = Device->DeviceGuid;
 982     I2cDeviceContext->I2cIo.DeviceIndex      = Device->DeviceIndex;
 983     I2cDeviceContext->I2cIo.HardwareRevision = Device->HardwareRevision;
 984     I2cDeviceContext->I2cIo.I2cControllerCapabilities = I2cBusContext->I2cHost->I2cControllerCapabilities;
 985
 986     //
 987     //  Build the device path
 988     //
 989     Status = I2cBusDevicePathAppend (I2cDeviceContext, BuildControllerNode);
 990     ASSERT_EFI_ERROR (Status);
 991     if (EFI_ERROR (Status)) {
 992       continue;
 993     }
 994
 995     //
 996     //  Install the protocol
 997     //
 998     Status = gBS->InstallMultipleProtocolInterfaces (
 999               &I2cDeviceContext->Handle,
1000               &gEfiI2cIoProtocolGuid,
1001               &I2cDeviceContext->I2cIo,
1002               &gEfiDevicePathProtocolGuid,
1003               I2cDeviceContext->DevicePath,
1004               NULL );
1005     if (EFI_ERROR (Status)) {
1006       //
1007       // Free resources for this I2C device
1008       //
1009       ReleaseI2cDeviceContext (I2cDeviceContext);
1010       continue;
1011     }
1012
1013     //
1014     // Create the child handle
1015     //
1016     Status = gBS->OpenProtocol (
1017                     Controller,
1018                     &gEfiI2cHostProtocolGuid,
1019                     (VOID **) &I2cBusContext->I2cHost,
1020                     I2cBusContext->DriverBindingHandle,
1021                     I2cDeviceContext->Handle,
1022                     EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
1023                     );
1024     if (EFI_ERROR (Status)) {
1025       Status = gBS->UninstallMultipleProtocolInterfaces (
1026                       I2cDeviceContext->Handle,
1027                       &gEfiDevicePathProtocolGuid,
1028                       I2cDeviceContext->DevicePath,
1029                       &gEfiI2cIoProtocolGuid,
1030                       &I2cDeviceContext->I2cIo,
1031                       NULL
1032                       );
1033       //
1034       // Free resources for this I2C device
1035       //
1036       ReleaseI2cDeviceContext (I2cDeviceContext);
1037       continue;
1038     }
1039
1040     if (RemainingDevicePath != NULL) {
1041       //
1042       // Child has been created successfully
1043       //
1044       break;
1045     }
1046   }
1047
1048   return Status;
1049 }
1050
1051
1052 /**
1053   Queue an I2C transaction for execution on the I2C device.
1054
1055   This routine must be called at or below TPL_NOTIFY.  For synchronous
1056   requests this routine must be called at or below TPL_CALLBACK.
1057
1058   This routine queues an I2C transaction to the I2C controller for
1059   execution on the I2C bus.
1060
1061   When Event is NULL, QueueRequest() operates synchronously and returns
1062   the I2C completion status as its return value.
1063
1064   When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS
1065   indicating that the asynchronous I2C transaction was queued.  The values
1066   above are returned in the buffer pointed to by I2cStatus upon the
1067   completion of the I2C transaction when I2cStatus is not NULL.
1068
1069   The upper layer driver writer provides the following to the platform
1070   vendor:
1071
1072   1.  Vendor specific GUID for the I2C part
1073   2.  Guidance on proper construction of the slave address array when the
1074       I2C device uses more than one slave address.  The I2C bus protocol
1075       uses the SlaveAddressIndex to perform relative to physical address
1076       translation to access the blocks of hardware within the I2C device.
1077
1078   @param[in] This               Pointer to an EFI_I2C_IO_PROTOCOL structure.
1079   @param[in] SlaveAddressIndex  Index value into an array of slave addresses
1080                                 for the I2C device.  The values in the array
1081                                 are specified by the board designer, with the
1082                                 third party I2C device driver writer providing
1083                                 the slave address order.
1084
1085                                 For devices that have a single slave address,
1086                                 this value must be zero.  If the I2C device
1087                                 uses more than one slave address then the
1088                                 third party (upper level) I2C driver writer
1089                                 needs to specify the order of entries in the
1090                                 slave address array.
1091
1092                                 \ref ThirdPartyI2cDrivers "Third Party I2C
1093                                 Drivers" section in I2cMaster.h.
1094   @param[in] Event              Event to signal for asynchronous transactions,
1095                                 NULL for synchronous transactions
1096   @param[in] RequestPacket      Pointer to an EFI_I2C_REQUEST_PACKET structure
1097                                 describing the I2C transaction
1098   @param[out] I2cStatus         Optional buffer to receive the I2C transaction
1099                                 completion status
1100
1101   @retval EFI_SUCCESS           The asynchronous transaction was successfully
1102                                 queued when Event is not NULL.
1103   @retval EFI_SUCCESS           The transaction completed successfully when
1104                                 Event is NULL.
1105   @retval EFI_BAD_BUFFER_SIZE   The RequestPacket->LengthInBytes value is too
1106                                 large.
1107   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the
1108                                 transaction.
1109   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
1110   @retval EFI_NO_MAPPING        The EFI_I2C_HOST_PROTOCOL could not set the
1111                                 bus configuration required to access this I2C
1112                                 device.
1113   @retval EFI_NO_RESPONSE       The I2C device is not responding to the slave
1114                                 address selected by SlaveAddressIndex.
1115                                 EFI_DEVICE_ERROR will be returned if the
1116                                 controller cannot distinguish when the NACK
1117                                 occurred.
1118   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C transaction
1119   @retval EFI_UNSUPPORTED       The controller does not support the requested
1120                                 transaction.
1121
1122 **/
1123 EFI_STATUS
1124 EFIAPI
1125 I2cBusQueueRequest (
1126   IN CONST EFI_I2C_IO_PROTOCOL  *This,
1127   IN UINTN                      SlaveAddressIndex,
1128   IN EFI_EVENT                  Event               OPTIONAL,
1129   IN EFI_I2C_REQUEST_PACKET     *RequestPacket,
1130   OUT EFI_STATUS                *I2cStatus          OPTIONAL
1131   )
1132 {
1133   CONST EFI_I2C_DEVICE        *I2cDevice;
1134   I2C_BUS_CONTEXT             *I2cBusContext;
1135   CONST EFI_I2C_HOST_PROTOCOL *I2cHost;
1136   I2C_DEVICE_CONTEXT          *I2cDeviceContext;
1137   EFI_STATUS                  Status;
1138
1139   if (RequestPacket == NULL) {
1140     return EFI_INVALID_PARAMETER;
1141   }
1142
1143   //
1144   //  Validate the I2C slave index
1145   //
1146   I2cDeviceContext = I2C_DEVICE_CONTEXT_FROM_PROTOCOL (This);
1147   I2cDevice        = I2cDeviceContext->I2cDevice;
1148   if ( SlaveAddressIndex >= I2cDevice->SlaveAddressCount ) {
1149     return EFI_INVALID_PARAMETER;
1150   }
1151
1152   //
1153   //  Locate the I2c Host Protocol to queue request
1154   //
1155   I2cBusContext = I2cDeviceContext->I2cBusContext;
1156   I2cHost       = I2cBusContext->I2cHost;
1157
1158   //
1159   //  Start the I2C operation
1160   //
1161   Status = I2cHost->QueueRequest (
1162                       I2cHost,
1163                       I2cDevice->I2cBusConfiguration,
1164                       I2cDevice->SlaveAddressArray [SlaveAddressIndex],
1165                       Event,
1166                       RequestPacket,
1167                       I2cStatus
1168                       );
1169
1170   return Status;
1171 }
1172
1173 /**
1174   Release all the resources allocated for the I2C device.
1175
1176   This function releases all the resources allocated for the I2C device.
1177
1178   @param  I2cDeviceContext         The I2C child device involved for the operation.
1179
1180 **/
1181 VOID
1182 ReleaseI2cDeviceContext (
1183   IN I2C_DEVICE_CONTEXT          *I2cDeviceContext
1184   )
1185 {
1186   if (I2cDeviceContext == NULL) {
1187     return;
1188   }
1189
1190   if (I2cDeviceContext->DevicePath != NULL) {
1191     FreePool (I2cDeviceContext->DevicePath);
1192   }
1193
1194   FreePool (I2cDeviceContext);
1195 }
1196
1197 /**
1198   Unregister an I2C device.
1199
1200   This function removes the protocols installed on the controller handle and
1201   frees the resources allocated for the I2C device.
1202
1203   @param  This                  The pointer to EFI_DRIVER_BINDING_PROTOCOL instance.
1204   @param  Controller            The controller handle of the I2C device.
1205   @param  Handle                The child handle.
1206
1207   @retval EFI_SUCCESS           The I2C device is successfully unregistered.
1208   @return Others                Some error occurs when unregistering the I2C device.
1209
1210 **/
1211 EFI_STATUS
1212 UnRegisterI2cDevice (
1213   IN  EFI_DRIVER_BINDING_PROTOCOL    *This,
1214   IN  EFI_HANDLE                     Controller,
1215   IN  EFI_HANDLE                     Handle
1216   )
1217 {
1218   EFI_STATUS                  Status;
1219   I2C_DEVICE_CONTEXT          *I2cDeviceContext;
1220   EFI_I2C_IO_PROTOCOL         *I2cIo;
1221   EFI_I2C_HOST_PROTOCOL       *I2cHost;
1222
1223   I2cIo = NULL;
1224
1225   Status = gBS->OpenProtocol (
1226                   Handle,
1227                   &gEfiI2cIoProtocolGuid,
1228                   (VOID **) &I2cIo,
1229                   This->DriverBindingHandle,
1230                   Controller,
1231                   EFI_OPEN_PROTOCOL_GET_PROTOCOL
1232                   );
1233   if (EFI_ERROR (Status)) {
1234     return Status;
1235   }
1236
1237   //
1238   // Get I2c device context data.
1239   //
1240   I2cDeviceContext = I2C_DEVICE_CONTEXT_FROM_PROTOCOL (I2cIo);
1241
1242   //
1243   // Close the child handle
1244   //
1245   gBS->CloseProtocol (
1246          Controller,
1247          &gEfiI2cHostProtocolGuid,
1248          This->DriverBindingHandle,
1249          Handle
1250          );
1251
1252   //
1253   // The I2C Bus driver installs the I2C Io and Device Path Protocol in the DriverBindingStart().
1254   // Here should uninstall them.
1255   //
1256   Status = gBS->UninstallMultipleProtocolInterfaces (
1257                   Handle,
1258                   &gEfiDevicePathProtocolGuid,
1259                   I2cDeviceContext->DevicePath,
1260                   &gEfiI2cIoProtocolGuid,
1261                   &I2cDeviceContext->I2cIo,
1262                   NULL
1263                   );
1264
1265   if (EFI_ERROR (Status)) {
1266     //
1267     // Keep parent and child relationship
1268     //
1269     gBS->OpenProtocol (
1270           Controller,
1271           &gEfiI2cHostProtocolGuid,
1272           (VOID **) &I2cHost,
1273           This->DriverBindingHandle,
1274           Handle,
1275           EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
1276           );
1277     return Status;
1278   }
1279
1280   //
1281   // Free resources for this I2C device
1282   //
1283   ReleaseI2cDeviceContext (I2cDeviceContext);
1284
1285   return EFI_SUCCESS;
1286 }
1287
1288 /**
1289   Create a path for the I2C device
1290
1291   Append the I2C slave path to the I2C master controller path.
1292
1293   @param[in] I2cDeviceContext           Address of an I2C_DEVICE_CONTEXT structure.
1294   @param[in] BuildControllerNode        Flag to build controller node in device path.
1295
1296   @retval EFI_SUCCESS           The I2C device path is built successfully.
1297   @return Others                It is failed to built device path.
1298
1299 **/
1300 EFI_STATUS
1301 I2cBusDevicePathAppend (
1302   IN I2C_DEVICE_CONTEXT     *I2cDeviceContext,
1303   IN BOOLEAN                BuildControllerNode
1304   )
1305 {
1306   EFI_DEVICE_PATH_PROTOCOL  *PreviousDevicePath;
1307
1308   PreviousDevicePath = NULL;
1309
1310   //
1311   // Build vendor device path
1312   //
1313   CopyMem (&gVendorDevicePathTemplate.Guid, I2cDeviceContext->I2cDevice->DeviceGuid, sizeof (EFI_GUID));
1314   I2cDeviceContext->DevicePath                    = AppendDevicePathNode (
1315                                                       I2cDeviceContext->I2cBusContext->ParentDevicePath,
1316                                                       (EFI_DEVICE_PATH_PROTOCOL *) &gVendorDevicePathTemplate
1317                                                       );
1318   ASSERT (I2cDeviceContext->DevicePath != NULL);
1319   if (I2cDeviceContext->DevicePath == NULL) {
1320     return EFI_OUT_OF_RESOURCES;
1321   }
1322
1323   if ((BuildControllerNode) && (I2cDeviceContext->DevicePath != NULL)) {
1324     //
1325     // Build the final I2C device path with controller node
1326     //
1327     PreviousDevicePath = I2cDeviceContext->DevicePath;
1328     gControllerDevicePathTemplate.ControllerNumber = I2cDeviceContext->I2cDevice->DeviceIndex;
1329     I2cDeviceContext->DevicePath          = AppendDevicePathNode (
1330                                               I2cDeviceContext->DevicePath,
1331                                               (EFI_DEVICE_PATH_PROTOCOL *) &gControllerDevicePathTemplate
1332                                               );
1333     gBS->FreePool (PreviousDevicePath);
1334     ASSERT (I2cDeviceContext->DevicePath != NULL);
1335     if (I2cDeviceContext->DevicePath == NULL) {
1336       return EFI_OUT_OF_RESOURCES;
1337     }
1338   }
1339
1340   return EFI_SUCCESS;
1341 }
1342
1343 /**
1344   The user entry point for the I2C bus module. The user code starts with
1345   this function.
1346
1347   @param[in] ImageHandle    The firmware allocated handle for the EFI image.
1348   @param[in] SystemTable    A pointer to the EFI System Table.
1349
1350   @retval EFI_SUCCESS       The entry point is executed successfully.
1351   @retval other             Some error occurs when executing this entry point.
1352
1353 **/
1354 EFI_STATUS
1355 EFIAPI
1356 InitializeI2cBus(
1357   IN EFI_HANDLE           ImageHandle,
1358   IN EFI_SYSTEM_TABLE     *SystemTable
1359   )
1360 {
1361   EFI_STATUS              Status;
1362
1363   //
1364   // Install driver model protocol(s).
1365   //
1366   Status = EfiLibInstallDriverBindingComponentName2 (
1367              ImageHandle,
1368              SystemTable,
1369              &gI2cBusDriverBinding,
1370              NULL,
1371              &gI2cBusComponentName,
1372              &gI2cBusComponentName2
1373              );
1374   ASSERT_EFI_ERROR (Status);
1375
1376
1377   return Status;
1378 }
1379
1380 /**
1381   This is the unload handle for I2C bus module.
1382
1383   Disconnect the driver specified by ImageHandle from all the devices in the handle database.
1384   Uninstall all the protocols installed in the driver entry point.
1385
1386   @param[in] ImageHandle           The drivers' driver image.
1387
1388   @retval    EFI_SUCCESS           The image is unloaded.
1389   @retval    Others                Failed to unload the image.
1390
1391 **/
1392 EFI_STATUS
1393 EFIAPI
1394 I2cBusUnload (
1395   IN EFI_HANDLE             ImageHandle
1396   )
1397 {
1398   EFI_STATUS                        Status;
1399   EFI_HANDLE                        *DeviceHandleBuffer;
1400   UINTN                             DeviceHandleCount;
1401   UINTN                             Index;
1402   EFI_COMPONENT_NAME_PROTOCOL       *ComponentName;
1403   EFI_COMPONENT_NAME2_PROTOCOL      *ComponentName2;
1404
1405   //
1406   // Get the list of all I2C Controller handles in the handle database.
1407   // If there is an error getting the list, then the unload
1408   // operation fails.
1409   //
1410   Status = gBS->LocateHandleBuffer (
1411                   ByProtocol,
1412                   &gEfiI2cHostProtocolGuid,
1413                   NULL,
1414                   &DeviceHandleCount,
1415                   &DeviceHandleBuffer
1416                   );
1417
1418   if (!EFI_ERROR (Status)) {
1419     //
1420     // Disconnect the driver specified by Driver BindingHandle from all
1421     // the devices in the handle database.
1422     //
1423     for (Index = 0; Index < DeviceHandleCount; Index++) {
1424       Status = gBS->DisconnectController (
1425                       DeviceHandleBuffer[Index],
1426                       gI2cBusDriverBinding.DriverBindingHandle,
1427                       NULL
1428                       );
1429       if (EFI_ERROR (Status)) {
1430         goto Done;
1431       }
1432     }
1433   }
1434
1435   //
1436   // Uninstall all the protocols installed in the driver entry point
1437   //
1438   Status = gBS->UninstallMultipleProtocolInterfaces (
1439                   gI2cBusDriverBinding.DriverBindingHandle,
1440                   &gEfiDriverBindingProtocolGuid,
1441                   &gI2cBusDriverBinding,
1442                   NULL
1443                   );
1444   ASSERT_EFI_ERROR (Status);
1445
1446   //
1447   // Note we have to one by one uninstall the following protocols.
1448   // It's because some of them are optionally installed based on
1449   // the following PCD settings.
1450   //   gEfiMdePkgTokenSpaceGuid.PcdDriverDiagnosticsDisable
1451   //   gEfiMdePkgTokenSpaceGuid.PcdComponentNameDisable
1452   //   gEfiMdePkgTokenSpaceGuid.PcdDriverDiagnostics2Disable
1453   //   gEfiMdePkgTokenSpaceGuid.PcdComponentName2Disable
1454   //
1455   Status = gBS->HandleProtocol (
1456                   gI2cBusDriverBinding.DriverBindingHandle,
1457                   &gEfiComponentNameProtocolGuid,
1458                   (VOID **) &ComponentName
1459                   );
1460   if (!EFI_ERROR (Status)) {
1461     gBS->UninstallProtocolInterface (
1462            gI2cBusDriverBinding.DriverBindingHandle,
1463            &gEfiComponentNameProtocolGuid,
1464            ComponentName
1465            );
1466   }
1467
1468   Status = gBS->HandleProtocol (
1469                   gI2cBusDriverBinding.DriverBindingHandle,
1470                   &gEfiComponentName2ProtocolGuid,
1471                   (VOID **) &ComponentName2
1472                   );
1473   if (!EFI_ERROR (Status)) {
1474     gBS->UninstallProtocolInterface (
1475            gI2cBusDriverBinding.DriverBindingHandle,
1476            &gEfiComponentName2ProtocolGuid,
1477            ComponentName2
1478            );
1479   }
1480
1481   Status = EFI_SUCCESS;
1482
1483 Done:
1484   //
1485   // Free the buffer containing the list of handles from the handle database
1486   //
1487   if (DeviceHandleBuffer != NULL) {
1488     gBS->FreePool (DeviceHandleBuffer);
1489   }
1490
1491   return Status;
1492 }