OvmfPkg/VirtioGpuDxe/DriverBinding.c

   1 /** @file
   2
   3   Implement the Driver Binding Protocol and the Component Name 2 Protocol for
   4   the Virtio GPU hybrid driver.
   5
   6   Copyright (C) 2016, Red Hat, Inc.
   7
   8   This program and the accompanying materials are licensed and made available
   9   under the terms and conditions of the BSD License which accompanies this
  10   distribution. The full text of the license may be found at
  11   http://opensource.org/licenses/bsd-license.php
  12
  13   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
  14   WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16 **/
  17
  18 #include <Library/BaseMemoryLib.h>
  19 #include <Library/DevicePathLib.h>
  20 #include <Library/MemoryAllocationLib.h>
  21 #include <Library/PrintLib.h>
  22 #include <Library/UefiBootServicesTableLib.h>
  23 #include <Library/UefiLib.h>
  24 #include <Protocol/ComponentName2.h>
  25 #include <Protocol/DevicePath.h>
  26 #include <Protocol/DriverBinding.h>
  27 #include <Protocol/PciIo.h>
  28
  29 #include "VirtioGpu.h"
  30
  31 //
  32 // The device path node that describes the Video Output Device Attributes for
  33 // the single head (UEFI child handle) that we support.
  34 //
  35 // The ACPI_DISPLAY_ADR() macro corresponds to Table B-2, section "B.4.2 _DOD"
  36 // in the ACPI 3.0b spec, or more recently, to Table B-379, section "B.3.2
  37 // _DOD" in the ACPI 6.0 spec.
  38 //
  39 STATIC CONST ACPI_ADR_DEVICE_PATH mAcpiAdr = {
  40   {                                         // Header
  41     ACPI_DEVICE_PATH,                       //   Type
  42     ACPI_ADR_DP,                            //   SubType
  43     { sizeof mAcpiAdr, 0 },                 //   Length
  44   },
  45   ACPI_DISPLAY_ADR (                        // ADR
  46     1,                                      //   DeviceIdScheme: use the ACPI
  47                                             //     bit-field definitions
  48     0,                                      //   HeadId
  49     0,                                      //   NonVgaOutput
  50     1,                                      //   BiosCanDetect
  51     0,                                      //   VendorInfo
  52     ACPI_ADR_DISPLAY_TYPE_EXTERNAL_DIGITAL, //   Type
  53     0,                                      //   Port
  54     0                                       //   Index
  55     )
  56 };
  57
  58 //
  59 // Component Name 2 Protocol implementation.
  60 //
  61 STATIC CONST EFI_UNICODE_STRING_TABLE mDriverNameTable[] = {
  62   { "en", L"Virtio GPU Driver" },
  63   { NULL, NULL                 }
  64 };
  65
  66 STATIC
  67 EFI_STATUS
  68 EFIAPI
  69 VirtioGpuGetDriverName (
  70   IN  EFI_COMPONENT_NAME2_PROTOCOL *This,
  71   IN  CHAR8                        *Language,
  72   OUT CHAR16                       **DriverName
  73   )
  74 {
  75   return LookupUnicodeString2 (Language, This->SupportedLanguages,
  76            mDriverNameTable, DriverName, FALSE /* Iso639Language */);
  77 }
  78
  79 STATIC
  80 EFI_STATUS
  81 EFIAPI
  82 VirtioGpuGetControllerName (
  83   IN  EFI_COMPONENT_NAME2_PROTOCOL *This,
  84   IN  EFI_HANDLE                   ControllerHandle,
  85   IN  EFI_HANDLE                   ChildHandle       OPTIONAL,
  86   IN  CHAR8                        *Language,
  87   OUT CHAR16                       **ControllerName
  88   )
  89 {
  90   EFI_STATUS Status;
  91   VGPU_DEV   *VgpuDev;
  92
  93   //
  94   // Look up the VGPU_DEV "protocol interface" on ControllerHandle.
  95   //
  96   Status = gBS->OpenProtocol (ControllerHandle, &gEfiCallerIdGuid,
  97                   (VOID **)&VgpuDev, gImageHandle, ControllerHandle,
  98                   EFI_OPEN_PROTOCOL_GET_PROTOCOL);
  99   if (EFI_ERROR (Status)) {
 100     return Status;
 101   }
 102   //
 103   // Sanity check: if we found gEfiCallerIdGuid on ControllerHandle, then we
 104   // keep its Virtio Device Protocol interface open BY_DRIVER.
 105   //
 106   ASSERT_EFI_ERROR (EfiTestManagedDevice (ControllerHandle, gImageHandle,
 107                       &gVirtioDeviceProtocolGuid));
 108
 109   if (ChildHandle == NULL) {
 110     //
 111     // The caller is querying the name of the VGPU_DEV controller.
 112     //
 113     return LookupUnicodeString2 (Language, This->SupportedLanguages,
 114              VgpuDev->BusName, ControllerName, FALSE /* Iso639Language */);
 115   }
 116
 117   //
 118   // Otherwise, the caller is looking for the name of the GOP child controller.
 119   // Check if it is asking about the GOP child controller that we manage. (The
 120   // condition below covers the case when we haven't produced the GOP child
 121   // controller yet, or we've destroyed it since.)
 122   //
 123   if (VgpuDev->Child == NULL || ChildHandle != VgpuDev->Child->GopHandle) {
 124     return EFI_UNSUPPORTED;
 125   }
 126   //
 127   // Sanity check: our GOP child controller keeps the VGPU_DEV controller's
 128   // Virtio Device Protocol interface open BY_CHILD_CONTROLLER.
 129   //
 130   ASSERT_EFI_ERROR (EfiTestChildHandle (ControllerHandle, ChildHandle,
 131                       &gVirtioDeviceProtocolGuid));
 132
 133   return LookupUnicodeString2 (Language, This->SupportedLanguages,
 134            VgpuDev->Child->GopName, ControllerName,
 135            FALSE /* Iso639Language */);
 136 }
 137
 138 STATIC CONST EFI_COMPONENT_NAME2_PROTOCOL mComponentName2 = {
 139   VirtioGpuGetDriverName,
 140   VirtioGpuGetControllerName,
 141   "en"                       // SupportedLanguages (RFC 4646)
 142 };
 143
 144 //
 145 // Helper functions for the Driver Binding Protocol Implementation.
 146 //
 147 /**
 148   Format the VGPU_DEV controller name, to be looked up and returned by
 149   VirtioGpuGetControllerName().
 150
 151   @param[in] ControllerHandle  The handle that identifies the VGPU_DEV
 152                                controller.
 153
 154   @param[in] AgentHandle       The handle of the agent that will attempt to
 155                                temporarily open the PciIo protocol. This is the
 156                                DriverBindingHandle member of the
 157                                EFI_DRIVER_BINDING_PROTOCOL whose Start()
 158                                function is calling this function.
 159
 160   @param[in] DevicePath        The device path that is installed on
 161                                ControllerHandle.
 162
 163   @param[out] ControllerName   A dynamically allocated unicode string that
 164                                unconditionally says "Virtio GPU Device", with a
 165                                PCI Segment:Bus:Device.Function location
 166                                optionally appended. The latter part is only
 167                                produced if DevicePath contains at least one
 168                                PciIo node; in that case, the most specific such
 169                                node is used for retrieving the location info.
 170                                The caller is responsible for freeing
 171                                ControllerName after use.
 172
 173   @retval EFI_SUCCESS           ControllerName has been formatted.
 174
 175   @retval EFI_OUT_OF_RESOURCES  Failed to allocate memory for ControllerName.
 176 **/
 177 STATIC
 178 EFI_STATUS
 179 FormatVgpuDevName (
 180   IN  EFI_HANDLE               ControllerHandle,
 181   IN  EFI_HANDLE               AgentHandle,
 182   IN  EFI_DEVICE_PATH_PROTOCOL *DevicePath,
 183   OUT CHAR16                   **ControllerName
 184   )
 185 {
 186   EFI_HANDLE          PciIoHandle;
 187   EFI_PCI_IO_PROTOCOL *PciIo;
 188   UINTN               Segment, Bus, Device, Function;
 189   STATIC CONST CHAR16 ControllerNameStem[] = L"Virtio GPU Device";
 190   UINTN               ControllerNameSize;
 191
 192   if (EFI_ERROR (gBS->LocateDevicePath (&gEfiPciIoProtocolGuid, &DevicePath,
 193                         &PciIoHandle)) ||
 194       EFI_ERROR (gBS->OpenProtocol (PciIoHandle, &gEfiPciIoProtocolGuid,
 195                         (VOID **)&PciIo, AgentHandle, ControllerHandle,
 196                         EFI_OPEN_PROTOCOL_GET_PROTOCOL)) ||
 197       EFI_ERROR (PciIo->GetLocation (PciIo, &Segment, &Bus, &Device,
 198                           &Function))) {
 199     //
 200     // Failed to retrieve location info, return verbatim copy of static string.
 201     //
 202     *ControllerName = AllocateCopyPool (sizeof ControllerNameStem,
 203                         ControllerNameStem);
 204     return (*ControllerName == NULL) ? EFI_OUT_OF_RESOURCES : EFI_SUCCESS;
 205   }
 206   //
 207   // Location info available, format ControllerName dynamically.
 208   //
 209   ControllerNameSize = sizeof ControllerNameStem + // includes L'\0'
 210                        sizeof (CHAR16) * (1 + 4 +  // Segment
 211                                           1 + 2 +  // Bus
 212                                           1 + 2 +  // Device
 213                                           1 + 1    // Function
 214                                           );
 215   *ControllerName = AllocatePool (ControllerNameSize);
 216   if (*ControllerName == NULL) {
 217     return EFI_OUT_OF_RESOURCES;
 218   }
 219
 220   UnicodeSPrintAsciiFormat (*ControllerName, ControllerNameSize,
 221     "%s %04x:%02x:%02x.%x", ControllerNameStem, (UINT32)Segment, (UINT32)Bus,
 222     (UINT32)Device, (UINT32)Function);
 223   return EFI_SUCCESS;
 224 }
 225
 226 /**
 227   Dynamically allocate and initialize the VGPU_GOP child object within an
 228   otherwise configured parent VGPU_DEV object.
 229
 230   This function adds a BY_CHILD_CONTROLLER reference to ParentBusController's
 231   VIRTIO_DEVICE_PROTOCOL interface.
 232
 233   @param[in,out] ParentBus        The pre-initialized VGPU_DEV object that the
 234                                   newly created VGPU_GOP object will be the
 235                                   child of.
 236
 237   @param[in] ParentDevicePath     The device path protocol instance that is
 238                                   installed on ParentBusController.
 239
 240   @param[in] ParentBusController  The UEFI controller handle on which the
 241                                   ParentBus VGPU_DEV object and the
 242                                   ParentDevicePath device path protocol are
 243                                   installed.
 244
 245   @param[in] DriverBindingHandle  The DriverBindingHandle member of
 246                                   EFI_DRIVER_BINDING_PROTOCOL whose Start()
 247                                   function is calling this function. It is
 248                                   passed as AgentHandle to gBS->OpenProtocol()
 249                                   when creating the BY_CHILD_CONTROLLER
 250                                   reference.
 251
 252   @retval EFI_SUCCESS           ParentBus->Child has been created and
 253                                 populated, and ParentBus->Child->GopHandle now
 254                                 references ParentBusController->VirtIo
 255                                 BY_CHILD_CONTROLLER.
 256
 257   @retval EFI_OUT_OF_RESOURCES  Memory allocation failed.
 258
 259   @return                       Error codes from underlying functions.
 260 **/
 261 STATIC
 262 EFI_STATUS
 263 InitVgpuGop (
 264   IN OUT VGPU_DEV                 *ParentBus,
 265   IN     EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath,
 266   IN     EFI_HANDLE               ParentBusController,
 267   IN     EFI_HANDLE               DriverBindingHandle
 268   )
 269 {
 270   VGPU_GOP            *VgpuGop;
 271   EFI_STATUS          Status;
 272   CHAR16              *ParentBusName;
 273   STATIC CONST CHAR16 NameSuffix[] = L" Head #0";
 274   UINTN               NameSize;
 275   CHAR16              *Name;
 276   EFI_TPL             OldTpl;
 277   VOID                *ParentVirtIo;
 278
 279   VgpuGop = AllocateZeroPool (sizeof *VgpuGop);
 280   if (VgpuGop == NULL) {
 281     return EFI_OUT_OF_RESOURCES;
 282   }
 283
 284   VgpuGop->Signature = VGPU_GOP_SIG;
 285   VgpuGop->ParentBus = ParentBus;
 286
 287   //
 288   // Format a human-readable controller name for VGPU_GOP, and stash it for
 289   // VirtioGpuGetControllerName() to look up. We simply append NameSuffix to
 290   // ParentBus->BusName.
 291   //
 292   Status = LookupUnicodeString2 ("en", mComponentName2.SupportedLanguages,
 293              ParentBus->BusName, &ParentBusName, FALSE /* Iso639Language */);
 294   ASSERT_EFI_ERROR (Status);
 295   NameSize = StrSize (ParentBusName) - sizeof (CHAR16) + sizeof NameSuffix;
 296   Name = AllocatePool (NameSize);
 297   if (Name == NULL) {
 298     Status = EFI_OUT_OF_RESOURCES;
 299     goto FreeVgpuGop;
 300   }
 301   UnicodeSPrintAsciiFormat (Name, NameSize, "%s%s", ParentBusName, NameSuffix);
 302   Status = AddUnicodeString2 ("en", mComponentName2.SupportedLanguages,
 303              &VgpuGop->GopName, Name, FALSE /* Iso639Language */);
 304   FreePool (Name);
 305   if (EFI_ERROR (Status)) {
 306     goto FreeVgpuGop;
 307   }
 308
 309   //
 310   // Create the child device path.
 311   //
 312   VgpuGop->GopDevicePath = AppendDevicePathNode (ParentDevicePath,
 313                              &mAcpiAdr.Header);
 314   if (VgpuGop->GopDevicePath == NULL) {
 315     Status = EFI_OUT_OF_RESOURCES;
 316     goto FreeVgpuGopName;
 317   }
 318
 319   //
 320   // Mask protocol notify callbacks until we're done.
 321   //
 322   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 323
 324   //
 325   // Create the child handle with the child device path.
 326   //
 327   Status = gBS->InstallProtocolInterface (&VgpuGop->GopHandle,
 328                   &gEfiDevicePathProtocolGuid, EFI_NATIVE_INTERFACE,
 329                   VgpuGop->GopDevicePath);
 330   if (EFI_ERROR (Status)) {
 331     goto FreeDevicePath;
 332   }
 333
 334   //
 335   // The child handle must present a reference to the parent handle's Virtio
 336   // Device Protocol interface.
 337   //
 338   Status = gBS->OpenProtocol (ParentBusController, &gVirtioDeviceProtocolGuid,
 339                   &ParentVirtIo, DriverBindingHandle, VgpuGop->GopHandle,
 340                   EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER);
 341   if (EFI_ERROR (Status)) {
 342     goto UninstallDevicePath;
 343   }
 344   ASSERT (ParentVirtIo == ParentBus->VirtIo);
 345
 346   //
 347   // Initialize our Graphics Output Protocol.
 348   //
 349   // Fill in the function members of VgpuGop->Gop from the template, then set
 350   // up the rest of the GOP infrastructure by calling SetMode() right now.
 351   //
 352   CopyMem (&VgpuGop->Gop, &mGopTemplate, sizeof mGopTemplate);
 353   Status = VgpuGop->Gop.SetMode (&VgpuGop->Gop, 0);
 354   if (EFI_ERROR (Status)) {
 355     goto CloseVirtIoByChild;
 356   }
 357
 358   //
 359   // Install the Graphics Output Protocol on the child handle.
 360   //
 361   Status = gBS->InstallProtocolInterface (&VgpuGop->GopHandle,
 362                   &gEfiGraphicsOutputProtocolGuid, EFI_NATIVE_INTERFACE,
 363                   &VgpuGop->Gop);
 364   if (EFI_ERROR (Status)) {
 365     goto UninitGop;
 366   }
 367
 368   //
 369   // We're done.
 370   //
 371   gBS->RestoreTPL (OldTpl);
 372   ParentBus->Child = VgpuGop;
 373   return EFI_SUCCESS;
 374
 375 UninitGop:
 376   ReleaseGopResources (VgpuGop, TRUE /* DisableHead */);
 377
 378 CloseVirtIoByChild:
 379   gBS->CloseProtocol (ParentBusController, &gVirtioDeviceProtocolGuid,
 380     DriverBindingHandle, VgpuGop->GopHandle);
 381
 382 UninstallDevicePath:
 383   gBS->UninstallProtocolInterface (VgpuGop->GopHandle,
 384          &gEfiDevicePathProtocolGuid, VgpuGop->GopDevicePath);
 385
 386 FreeDevicePath:
 387   gBS->RestoreTPL (OldTpl);
 388   FreePool (VgpuGop->GopDevicePath);
 389
 390 FreeVgpuGopName:
 391   FreeUnicodeStringTable (VgpuGop->GopName);
 392
 393 FreeVgpuGop:
 394   FreePool (VgpuGop);
 395
 396   return Status;
 397 }
 398
 399 /**
 400   Tear down and release the VGPU_GOP child object within the VGPU_DEV parent
 401   object.
 402
 403   This function removes the BY_CHILD_CONTROLLER reference from
 404   ParentBusController's VIRTIO_DEVICE_PROTOCOL interface.
 405
 406   @param[in,out] ParentBus        The VGPU_DEV object that the VGPU_GOP child
 407                                   object will be removed from.
 408
 409   @param[in] ParentBusController  The UEFI controller handle on which the
 410                                   ParentBus VGPU_DEV object is installed.
 411
 412   @param[in] DriverBindingHandle  The DriverBindingHandle member of
 413                                   EFI_DRIVER_BINDING_PROTOCOL whose Stop()
 414                                   function is calling this function. It is
 415                                   passed as AgentHandle to gBS->CloseProtocol()
 416                                   when removing the BY_CHILD_CONTROLLER
 417                                   reference.
 418 **/
 419 STATIC
 420 VOID
 421 UninitVgpuGop (
 422   IN OUT VGPU_DEV   *ParentBus,
 423   IN     EFI_HANDLE ParentBusController,
 424   IN     EFI_HANDLE DriverBindingHandle
 425   )
 426 {
 427   VGPU_GOP   *VgpuGop;
 428   EFI_STATUS Status;
 429
 430   VgpuGop = ParentBus->Child;
 431   Status = gBS->UninstallProtocolInterface (VgpuGop->GopHandle,
 432                   &gEfiGraphicsOutputProtocolGuid, &VgpuGop->Gop);
 433   ASSERT_EFI_ERROR (Status);
 434
 435   //
 436   // Uninitialize VgpuGop->Gop.
 437   //
 438   ReleaseGopResources (VgpuGop, TRUE /* DisableHead */);
 439
 440   Status = gBS->CloseProtocol (ParentBusController, &gVirtioDeviceProtocolGuid,
 441                   DriverBindingHandle, VgpuGop->GopHandle);
 442   ASSERT_EFI_ERROR (Status);
 443
 444   Status = gBS->UninstallProtocolInterface (VgpuGop->GopHandle,
 445                   &gEfiDevicePathProtocolGuid, VgpuGop->GopDevicePath);
 446   ASSERT_EFI_ERROR (Status);
 447
 448   FreePool (VgpuGop->GopDevicePath);
 449   FreeUnicodeStringTable (VgpuGop->GopName);
 450   FreePool (VgpuGop);
 451
 452   ParentBus->Child = NULL;
 453 }
 454
 455 //
 456 // Driver Binding Protocol Implementation.
 457 //
 458 STATIC
 459 EFI_STATUS
 460 EFIAPI
 461 VirtioGpuDriverBindingSupported (
 462   IN EFI_DRIVER_BINDING_PROTOCOL *This,
 463   IN EFI_HANDLE                  ControllerHandle,
 464   IN EFI_DEVICE_PATH_PROTOCOL    *RemainingDevicePath OPTIONAL
 465   )
 466 {
 467   EFI_STATUS             Status;
 468   VIRTIO_DEVICE_PROTOCOL *VirtIo;
 469
 470   //
 471   // - If RemainingDevicePath is NULL: the caller is interested in creating all
 472   //   child handles.
 473   // - If RemainingDevicePath points to an end node: the caller is not
 474   //   interested in creating any child handle.
 475   // - Otherwise, the caller would like to create the one child handle
 476   //   specified in RemainingDevicePath. In this case we have to see if the
 477   //   requested device path is supportable.
 478   //
 479   if (RemainingDevicePath != NULL &&
 480       !IsDevicePathEnd (RemainingDevicePath) &&
 481       (DevicePathNodeLength (RemainingDevicePath) != sizeof mAcpiAdr ||
 482        CompareMem (RemainingDevicePath, &mAcpiAdr, sizeof mAcpiAdr) != 0)) {
 483     return EFI_UNSUPPORTED;
 484   }
 485
 486   //
 487   // Open the Virtio Device Protocol interface on the controller, BY_DRIVER.
 488   //
 489   Status = gBS->OpenProtocol (ControllerHandle, &gVirtioDeviceProtocolGuid,
 490                   (VOID **)&VirtIo, This->DriverBindingHandle,
 491                   ControllerHandle, EFI_OPEN_PROTOCOL_BY_DRIVER);
 492   if (EFI_ERROR (Status)) {
 493     //
 494     // If this fails, then by default we cannot support ControllerHandle. There
 495     // is one exception: we've already bound the device, have not produced any
 496     // GOP child controller, and now the caller wants us to produce the child
 497     // controller (either specifically or as part of "all children"). That's
 498     // allowed.
 499     //
 500     if (Status == EFI_ALREADY_STARTED) {
 501       EFI_STATUS Status2;
 502       VGPU_DEV   *VgpuDev;
 503
 504       Status2 = gBS->OpenProtocol (ControllerHandle, &gEfiCallerIdGuid,
 505                        (VOID **)&VgpuDev, This->DriverBindingHandle,
 506                        ControllerHandle, EFI_OPEN_PROTOCOL_GET_PROTOCOL);
 507       ASSERT_EFI_ERROR (Status2);
 508
 509       if (VgpuDev->Child == NULL &&
 510           (RemainingDevicePath == NULL ||
 511            !IsDevicePathEnd (RemainingDevicePath))) {
 512         Status = EFI_SUCCESS;
 513       }
 514     }
 515
 516     return Status;
 517   }
 518
 519   //
 520   // First BY_DRIVER open; check the VirtIo revision and subsystem.
 521   //
 522   if (VirtIo->Revision < VIRTIO_SPEC_REVISION (1, 0, 0) ||
 523       VirtIo->SubSystemDeviceId != VIRTIO_SUBSYSTEM_GPU_DEVICE) {
 524     Status = EFI_UNSUPPORTED;
 525     goto CloseVirtIo;
 526   }
 527
 528   //
 529   // We'll need the device path of the VirtIo device both for formatting
 530   // VGPU_DEV.BusName and for populating VGPU_GOP.GopDevicePath.
 531   //
 532   Status = gBS->OpenProtocol (ControllerHandle, &gEfiDevicePathProtocolGuid,
 533                   NULL, This->DriverBindingHandle, ControllerHandle,
 534                   EFI_OPEN_PROTOCOL_TEST_PROTOCOL);
 535
 536 CloseVirtIo:
 537   gBS->CloseProtocol (ControllerHandle, &gVirtioDeviceProtocolGuid,
 538     This->DriverBindingHandle, ControllerHandle);
 539
 540   return Status;
 541 }
 542
 543 STATIC
 544 EFI_STATUS
 545 EFIAPI
 546 VirtioGpuDriverBindingStart (
 547   IN EFI_DRIVER_BINDING_PROTOCOL *This,
 548   IN EFI_HANDLE                  ControllerHandle,
 549   IN EFI_DEVICE_PATH_PROTOCOL    *RemainingDevicePath OPTIONAL
 550   )
 551 {
 552   EFI_STATUS               Status;
 553   VIRTIO_DEVICE_PROTOCOL   *VirtIo;
 554   BOOLEAN                  VirtIoBoundJustNow;
 555   VGPU_DEV                 *VgpuDev;
 556   EFI_DEVICE_PATH_PROTOCOL *DevicePath;
 557
 558   //
 559   // Open the Virtio Device Protocol.
 560   //
 561   // The result of this operation, combined with the checks in
 562   // VirtioGpuDriverBindingSupported(), uniquely tells us whether we are
 563   // binding the VirtIo controller on this call (with or without creating child
 564   // controllers), or else we're *only* creating child controllers.
 565   //
 566   Status = gBS->OpenProtocol (ControllerHandle, &gVirtioDeviceProtocolGuid,
 567                   (VOID **)&VirtIo, This->DriverBindingHandle,
 568                   ControllerHandle, EFI_OPEN_PROTOCOL_BY_DRIVER);
 569   if (EFI_ERROR (Status)) {
 570     //
 571     // The assertions below are based on the success of
 572     // VirtioGpuDriverBindingSupported(): we bound ControllerHandle earlier,
 573     // without producing child handles, and now we're producing the GOP child
 574     // handle only.
 575     //
 576     ASSERT (Status == EFI_ALREADY_STARTED);
 577
 578     Status = gBS->OpenProtocol (ControllerHandle, &gEfiCallerIdGuid,
 579                     (VOID **)&VgpuDev, This->DriverBindingHandle,
 580                     ControllerHandle, EFI_OPEN_PROTOCOL_GET_PROTOCOL);
 581     ASSERT_EFI_ERROR (Status);
 582
 583     ASSERT (VgpuDev->Child == NULL);
 584     ASSERT (
 585       RemainingDevicePath == NULL || !IsDevicePathEnd (RemainingDevicePath));
 586
 587     VirtIoBoundJustNow = FALSE;
 588   } else {
 589     VirtIoBoundJustNow = TRUE;
 590
 591     //
 592     // Allocate the private structure.
 593     //
 594     VgpuDev = AllocateZeroPool (sizeof *VgpuDev);
 595     if (VgpuDev == NULL) {
 596       Status = EFI_OUT_OF_RESOURCES;
 597       goto CloseVirtIo;
 598     }
 599     VgpuDev->VirtIo = VirtIo;
 600   }
 601
 602   //
 603   // Grab the VirtIo controller's device path. This is necessary regardless of
 604   // VirtIoBoundJustNow.
 605   //
 606   Status = gBS->OpenProtocol (ControllerHandle, &gEfiDevicePathProtocolGuid,
 607                   (VOID **)&DevicePath, This->DriverBindingHandle,
 608                   ControllerHandle, EFI_OPEN_PROTOCOL_GET_PROTOCOL);
 609   if (EFI_ERROR (Status)) {
 610     goto FreeVgpuDev;
 611   }
 612
 613   //
 614   // Create VGPU_DEV if we've bound the VirtIo controller right now (that is,
 615   // if we aren't *only* creating child handles).
 616   //
 617   if (VirtIoBoundJustNow) {
 618     CHAR16 *VgpuDevName;
 619
 620     //
 621     // Format a human-readable controller name for VGPU_DEV, and stash it for
 622     // VirtioGpuGetControllerName() to look up.
 623     //
 624     Status = FormatVgpuDevName (ControllerHandle, This->DriverBindingHandle,
 625                DevicePath, &VgpuDevName);
 626     if (EFI_ERROR (Status)) {
 627       goto FreeVgpuDev;
 628     }
 629     Status = AddUnicodeString2 ("en", mComponentName2.SupportedLanguages,
 630                &VgpuDev->BusName, VgpuDevName, FALSE /* Iso639Language */);
 631     FreePool (VgpuDevName);
 632     if (EFI_ERROR (Status)) {
 633       goto FreeVgpuDev;
 634     }
 635
 636     Status = VirtioGpuInit (VgpuDev);
 637     if (EFI_ERROR (Status)) {
 638       goto FreeVgpuDevBusName;
 639     }
 640
 641     Status = gBS->CreateEvent (EVT_SIGNAL_EXIT_BOOT_SERVICES, TPL_CALLBACK,
 642                     VirtioGpuExitBoot, VgpuDev /* NotifyContext */,
 643                     &VgpuDev->ExitBoot);
 644     if (EFI_ERROR (Status)) {
 645       goto UninitGpu;
 646     }
 647
 648     //
 649     // Install the VGPU_DEV "protocol interface" on ControllerHandle.
 650     //
 651     Status = gBS->InstallProtocolInterface (&ControllerHandle,
 652                     &gEfiCallerIdGuid, EFI_NATIVE_INTERFACE, VgpuDev);
 653     if (EFI_ERROR (Status)) {
 654       goto CloseExitBoot;
 655     }
 656
 657     if (RemainingDevicePath != NULL && IsDevicePathEnd (RemainingDevicePath)) {
 658       //
 659       // No child handle should be produced; we're done.
 660       //
 661       DEBUG ((EFI_D_INFO, "%a: bound VirtIo=%p without producing GOP\n",
 662         __FUNCTION__, (VOID *)VgpuDev->VirtIo));
 663       return EFI_SUCCESS;
 664     }
 665   }
 666
 667   //
 668   // Below we'll produce our single child handle: the caller requested it
 669   // either specifically, or as part of all child handles.
 670   //
 671   ASSERT (VgpuDev->Child == NULL);
 672   ASSERT (
 673     RemainingDevicePath == NULL || !IsDevicePathEnd (RemainingDevicePath));
 674
 675   Status = InitVgpuGop (VgpuDev, DevicePath, ControllerHandle,
 676              This->DriverBindingHandle);
 677   if (EFI_ERROR (Status)) {
 678     goto UninstallVgpuDev;
 679   }
 680
 681   //
 682   // We're done.
 683   //
 684   DEBUG ((EFI_D_INFO, "%a: produced GOP %a VirtIo=%p\n", __FUNCTION__,
 685     VirtIoBoundJustNow ? "while binding" : "for pre-bound",
 686     (VOID *)VgpuDev->VirtIo));
 687   return EFI_SUCCESS;
 688
 689 UninstallVgpuDev:
 690   if (VirtIoBoundJustNow) {
 691     gBS->UninstallProtocolInterface (ControllerHandle, &gEfiCallerIdGuid,
 692            VgpuDev);
 693   }
 694
 695 CloseExitBoot:
 696   if (VirtIoBoundJustNow) {
 697     gBS->CloseEvent (VgpuDev->ExitBoot);
 698   }
 699
 700 UninitGpu:
 701   if (VirtIoBoundJustNow) {
 702     VirtioGpuUninit (VgpuDev);
 703   }
 704
 705 FreeVgpuDevBusName:
 706   if (VirtIoBoundJustNow) {
 707     FreeUnicodeStringTable (VgpuDev->BusName);
 708   }
 709
 710 FreeVgpuDev:
 711   if (VirtIoBoundJustNow) {
 712     FreePool (VgpuDev);
 713   }
 714
 715 CloseVirtIo:
 716   if (VirtIoBoundJustNow) {
 717     gBS->CloseProtocol (ControllerHandle, &gVirtioDeviceProtocolGuid,
 718       This->DriverBindingHandle, ControllerHandle);
 719   }
 720
 721   return Status;
 722 }
 723
 724 STATIC
 725 EFI_STATUS
 726 EFIAPI
 727 VirtioGpuDriverBindingStop (
 728   IN  EFI_DRIVER_BINDING_PROTOCOL *This,
 729   IN  EFI_HANDLE                  ControllerHandle,
 730   IN  UINTN                       NumberOfChildren,
 731   IN  EFI_HANDLE                  *ChildHandleBuffer OPTIONAL
 732   )
 733 {
 734   EFI_STATUS Status;
 735   VGPU_DEV   *VgpuDev;
 736
 737   //
 738   // Look up the VGPU_DEV "protocol interface" on ControllerHandle.
 739   //
 740   Status = gBS->OpenProtocol (ControllerHandle, &gEfiCallerIdGuid,
 741                   (VOID **)&VgpuDev, This->DriverBindingHandle,
 742                   ControllerHandle, EFI_OPEN_PROTOCOL_GET_PROTOCOL);
 743   if (EFI_ERROR (Status)) {
 744     return Status;
 745   }
 746   //
 747   // Sanity check: if we found gEfiCallerIdGuid on ControllerHandle, then we
 748   // keep its Virtio Device Protocol interface open BY_DRIVER.
 749   //
 750   ASSERT_EFI_ERROR (EfiTestManagedDevice (ControllerHandle,
 751                       This->DriverBindingHandle, &gVirtioDeviceProtocolGuid));
 752
 753   switch (NumberOfChildren) {
 754   case 0:
 755     //
 756     // The caller wants us to unbind the VirtIo controller.
 757     //
 758     if (VgpuDev->Child != NULL) {
 759       //
 760       // We still have the GOP child.
 761       //
 762       Status = EFI_DEVICE_ERROR;
 763       break;
 764     }
 765
 766     DEBUG ((EFI_D_INFO, "%a: unbinding GOP-less VirtIo=%p\n", __FUNCTION__,
 767       (VOID *)VgpuDev->VirtIo));
 768
 769     Status = gBS->UninstallProtocolInterface (ControllerHandle,
 770                     &gEfiCallerIdGuid, VgpuDev);
 771     ASSERT_EFI_ERROR (Status);
 772
 773     Status = gBS->CloseEvent (VgpuDev->ExitBoot);
 774     ASSERT_EFI_ERROR (Status);
 775
 776     VirtioGpuUninit (VgpuDev);
 777     FreeUnicodeStringTable (VgpuDev->BusName);
 778     FreePool (VgpuDev);
 779
 780     Status = gBS->CloseProtocol (ControllerHandle, &gVirtioDeviceProtocolGuid,
 781                     This->DriverBindingHandle, ControllerHandle);
 782     ASSERT_EFI_ERROR (Status);
 783     break;
 784
 785   case 1:
 786     //
 787     // The caller wants us to destroy our child GOP controller.
 788     //
 789     if (VgpuDev->Child == NULL ||
 790         ChildHandleBuffer[0] != VgpuDev->Child->GopHandle) {
 791       //
 792       // We have no child controller at the moment, or it differs from the one
 793       // the caller wants us to destroy. I.e., we don't own the child
 794       // controller passed in.
 795       //
 796       Status = EFI_DEVICE_ERROR;
 797       break;
 798     }
 799     //
 800     // Sanity check: our GOP child controller keeps the VGPU_DEV controller's
 801     // Virtio Device Protocol interface open BY_CHILD_CONTROLLER.
 802     //
 803     ASSERT_EFI_ERROR (EfiTestChildHandle (ControllerHandle,
 804                         VgpuDev->Child->GopHandle,
 805                         &gVirtioDeviceProtocolGuid));
 806
 807     DEBUG ((EFI_D_INFO, "%a: destroying GOP under VirtIo=%p\n", __FUNCTION__,
 808       (VOID *)VgpuDev->VirtIo));
 809     UninitVgpuGop (VgpuDev, ControllerHandle, This->DriverBindingHandle);
 810     break;
 811
 812   default:
 813     //
 814     // Impossible, we never produced more than one child.
 815     //
 816     Status = EFI_DEVICE_ERROR;
 817     break;
 818   }
 819   return Status;
 820 }
 821
 822 STATIC EFI_DRIVER_BINDING_PROTOCOL mDriverBinding = {
 823   VirtioGpuDriverBindingSupported,
 824   VirtioGpuDriverBindingStart,
 825   VirtioGpuDriverBindingStop,
 826   0x10,                            // Version
 827   NULL,                            // ImageHandle, overwritten in entry point
 828   NULL                             // DriverBindingHandle, ditto
 829 };
 830
 831 //
 832 // Entry point of the driver.
 833 //
 834 EFI_STATUS
 835 EFIAPI
 836 VirtioGpuEntryPoint (
 837   IN EFI_HANDLE       ImageHandle,
 838   IN EFI_SYSTEM_TABLE *SystemTable
 839   )
 840 {
 841   return EfiLibInstallDriverBindingComponentName2 (ImageHandle, SystemTable,
 842            &mDriverBinding, ImageHandle, NULL /* ComponentName */,
 843            &mComponentName2);
 844 }