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