Vlv2TbltDevicePkg/PlatformDxe/Observable/Observable.c

   1 /*++
   2   This file contains 'Framework Code' and is licensed as such
   3   under the terms of your license agreement with Intel or your
   4   vendor.  This file may not be modified, except as allowed by
   5   additional terms of your license agreement.
   6 --*/
   7 /*++
   8
   9 Copyright (c)  2010  - 2014, Intel Corporation. All rights reserved
  10
  11   This program and the accompanying materials are licensed and made available under
  12   the terms and conditions of the BSD License that accompanies this distribution.
  13   The full text of the license may be found at
  14   http://opensource.org/licenses/bsd-license.php.
  15
  16   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  17   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  18
  19
  20
  21 Module Name:
  22
  23   Observable.c
  24
  25 Abstract:
  26
  27   The following contains all of the implementation for the Observable protocol. The
  28   protocol uses the observer design pattern to provide a way to publish events and
  29   to subscribe to those events so that a callback will be performed at the time of
  30   the event. The observables and subscribers are maintained by the static tree,
  31   mObservableDb. The difference between this protocol and the existing event protocol
  32   that exists within the EFI framework is that this protocol allows for parameters
  33   to be passed to the subscribed callbacks that can contain up to date context.
  34
  35 --*/
  36
  37 #include "Observable.h"
  38
  39 static OBS_TREE*                mObservableDb = NULL;
  40 static EFI_HANDLE               mObservableHandle = NULL;
  41 static OBS_OBSERVABLE_PROTOCOL  mObservable = {
  42   AddObservable,
  43   RemoveObservable,
  44   Subscribe,
  45   Unsubscribe,
  46   Publish,
  47   RemoveAllObservables
  48 };
  49
  50 /** Install observable protocol.
  51  *
  52  * Install interface and initialize the observable protocol.
  53  *
  54  * @param   VOID          No parameters.
  55  *
  56  * @return  EFI_SUCCESS   Successfully installed and initialized the protocol.
  57  **/
  58 EFI_STATUS
  59 InitializeObservableProtocol(
  60   VOID
  61   )
  62 {
  63   EFI_STATUS  Status;
  64
  65   //
  66   // Install protocol.
  67   //
  68   Status = gBS->InstallProtocolInterface (
  69                   &mObservableHandle,
  70                   &gObservableProtocolGuid,
  71                   EFI_NATIVE_INTERFACE,
  72                   &mObservable
  73                   );
  74
  75   return Status;
  76 }
  77
  78 /** Deletes a subscriber
  79  *
  80  * This function removes the subscriber pointed to by Head.
  81  *
  82  * @param   OBS_TREE*     Head    Points to the current subscriber.
  83  *
  84  * @return  OBS_TREE*     Returns the tree after successfully removing the subscriber.
  85  **/
  86 OBS_LEAF*
  87 DeleteSubscriber(
  88   OBS_LEAF* Head
  89   )
  90 {
  91   OBS_LEAF* Temp;
  92
  93   if (Head) {
  94     Temp = Head;
  95     Head = Head->Next;
  96     gBS->FreePool(Temp);
  97   }
  98
  99   return Head;
 100 }
 101
 102 /** Finds and deletes all subscribers
 103  *
 104  * This function iterates recursively through the existing subscribers and delets them all.
 105  *
 106  * @param   OBS_TREE*     Head    Points to the current subscriber.
 107  *
 108  * @return  OBS_TREE*     Returns the tree after successfully removing the subscribers.
 109  **/
 110 OBS_LEAF*
 111 DeleteAllSubscribers(
 112   OBS_LEAF* Head
 113   )
 114 {
 115   if (Head) {
 116     if (Head->Next) {
 117       //
 118       // We aren't at the end of the list yet.
 119       //
 120       Head->Next = DeleteAllSubscribers(Head->Next);
 121     }
 122
 123     //
 124     // At the end, so delete the subscriber.
 125     //
 126     Head = DeleteSubscriber(Head);
 127   }
 128
 129   return Head;
 130 }
 131
 132 /** Deletes an observable
 133  *
 134  * This function removes the observable pointed to by Head.
 135  *
 136  * @param   OBS_TREE*     Head    Points to the current observable.
 137  *
 138  * @return  OBS_TREE*     Returns the tree after successfully removing the observable.
 139  **/
 140 OBS_TREE*
 141 DeleteObservable(
 142   OBS_TREE* Head
 143   )
 144 {
 145   OBS_TREE* Temp;
 146
 147   if (Head) {
 148     Temp = Head;
 149     Head = Head->Next;
 150     gBS->FreePool(Temp);
 151   }
 152
 153   return Head;
 154 }
 155
 156 /** Finds and deletes all observables
 157  *
 158  * This function iterates recursively through the existing observables database and, starting with
 159  * the last most observable, deletes all of its subscribers, then deletes the observable itself.
 160  *
 161  * @param   OBS_TREE*     Head    Points to the current observable.
 162  *
 163  * @return  OBS_TREE*     Returns the tree after successfully removing the observables.
 164  **/
 165 OBS_TREE*
 166 DeleteAllObservables(
 167   OBS_TREE* Head
 168   )
 169 {
 170   if (Head) {
 171     if (Head->Next) {
 172       //
 173       // We aren't at the end of the list yet.
 174       //
 175       Head->Next = DeleteAllObservables(Head->Next);
 176     }
 177
 178     //
 179     // This is the end of the list of observables.
 180     //
 181     Head->Leaf = DeleteAllSubscribers(Head->Leaf);
 182
 183     //
 184     // Subscribers are deleted, so now delete the observable.
 185     //
 186     Head = DeleteObservable(Head);
 187   }
 188
 189   return Head;
 190 }
 191
 192 /** Finds and deletes observable
 193  *
 194  * This function iterates recursively through the existing observable database in order to find the one
 195  * specified by ReferenceGuid so that it can be deleted. If the requested observable is found, before it
 196  * is deleted, all of the subscribers that are listening to this observable are deleted.
 197  *
 198  * @param   OBS_TREE*     Head              Points to the current observable.
 199  *          EFI_GUID      ReferenceGuid     Corresponds to the observable that we're looking for.
 200  *
 201  * @return  OBS_TREE*     Returns the tree after successfully removing (or not finding) the observable.
 202  **/
 203 OBS_TREE*
 204 FindAndDeleteObservable(
 205   OBS_TREE* Head,
 206   EFI_GUID  ReferenceGuid
 207   )
 208 {
 209   if (Head) {
 210     if (CompareMem(&(Head->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid)) == 0) {
 211       //
 212       // We found the observable. Delete all of it's subscribers, first.
 213       //
 214       Head->Leaf = DeleteAllSubscribers(Head->Leaf);
 215       //
 216       // Now we can safely remove the observable.
 217       //
 218       Head = DeleteObservable(Head);
 219     } else {
 220       //
 221       // Not found. Keep searching.
 222       //
 223       Head->Next = FindAndDeleteObservable(Head->Next, ReferenceGuid);
 224     }
 225   }
 226
 227   return Head;
 228 }
 229
 230 /** Finds and deletes subscriber
 231  *
 232  * This function iterates recursively through the existing subscribers that are listening to the
 233  * observable that was found when this function was called.
 234  *
 235  * @param   OBS_TREE*     Head              Points to the current subscriber.
 236  *          OBS_CALLBACK  CallbackInterface This is the subscriber that is requested be removed.
 237  *
 238  * @return  OBS_TREE*     Returns the tree after successfully removing (or not finding) the subscriber.
 239  **/
 240 OBS_LEAF*
 241 _FindAndDeleteSubscriber(
 242   OBS_LEAF*     Head,
 243   OBS_CALLBACK  CallbackInterface
 244   )
 245 {
 246   if (Head) {
 247     if (Head->Observer == CallbackInterface) {
 248       //
 249       // Found it. Now let's delete it.
 250       //
 251       Head = DeleteSubscriber(Head);
 252     } else {
 253       //
 254       // Not found. Keep searching.
 255       //
 256       Head->Next = _FindAndDeleteSubscriber(Head->Next, CallbackInterface);
 257     }
 258   }
 259
 260   return Head;
 261 }
 262
 263 /** Finds and deletes subscriber
 264  *
 265  * This function iterates recursively through the existing observables database until it either finds
 266  * a matching guid or reaches the end of the list. After finding a match, it calls a helper function,
 267  * _FindAndDeleteSubscriber. At this point, all responsibility for finding and deleting the subscriber
 268  * lies on the helper function.
 269  *
 270  * @param   OBS_TREE*     Head              Points to the current observable.
 271  *          EFI_GUID      ReferenceGuid     Corresponds to the observable that we're looking for.
 272  *          OBS_CALLBACK  CallbackInterface This is the subscriber that is requested be removed.
 273  *
 274  * @return  OBS_TREE*     Returns the tree after successfully removing (or not finding) the subscriber.
 275  **/
 276 OBS_TREE*
 277 FindAndDeleteSubscriber(
 278   IN  OUT OBS_TREE*     Head,
 279   IN      EFI_GUID      ReferenceGuid,
 280   IN      OBS_CALLBACK  CallbackInterface
 281   )
 282 {
 283   if (Head) {
 284     if (CompareMem(&(Head->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid)) == 0) {
 285       //
 286       // We found the observer that matches ReferenceGuid. Find and delete the subscriber that is
 287       // listening to it.
 288       //
 289       Head->Leaf = _FindAndDeleteSubscriber(Head->Leaf, CallbackInterface);
 290     } else {
 291       //
 292       // Not found. Keep searching.
 293       //
 294       Head->Next = FindAndDeleteSubscriber(Head->Next, ReferenceGuid, CallbackInterface);
 295     }
 296   }
 297
 298   return Head;
 299 }
 300
 301 /** Remove all observables.
 302  *
 303  * Remove all observable guids and all interfaces subscribed to them.
 304  *
 305  * @param   VOID          No parameters.
 306  *
 307  * @return  EFI_SUCCESS   Successfully removed all observables and subscribed interfaces.
 308  **/
 309 EFI_STATUS
 310 EFIAPI
 311 RemoveAllObservables(
 312   VOID
 313   )
 314 {
 315   mObservableDb = DeleteAllObservables(mObservableDb);
 316
 317   return EFI_SUCCESS;
 318 }
 319
 320 /** Subscribe an interface with an observable guid.
 321  *
 322  * Use this to register a callback function with a guid. The function provided by CallbackInterface will be executed
 323  * whenever the appropriate observable instance specified by ReferenceGuid calls Publish.
 324  *
 325  * @param   EFI_GUID              ReferenceGuid       The observable guid that the callback interface will subscribe to.
 326  *          OBS_CASLLBACK         CallbackInterface   A pointer to the function that is subscribing to the observable.
 327  *
 328  * @return  EFI_SUCCESS           Successfully subscribed the interface to the observable guid.
 329  *          EFI_NOT_FOUND         No match could be found between the provided guid and existing observables.
 330  *          EFI_OUT_OF_RESOURCES  Could not subscribe to this observer due to resource limitations.
 331  *          EFI_INVALID_PARAMETER Interface is already subscribed to this observer.
 332  **/
 333 EFI_STATUS
 334 EFIAPI
 335 Subscribe (
 336   IN      EFI_GUID        ReferenceGuid,
 337   IN      OBS_CALLBACK    CallbackInterface
 338   )
 339 {
 340   EFI_STATUS  Status    = EFI_SUCCESS;
 341   OBS_TREE*   TempTree  = NULL;
 342   OBS_LEAF*   Last      = NULL;
 343   OBS_LEAF*   TempLeaf  = NULL;
 344   OBS_LEAF*   NewLeaf   = NULL;
 345   BOOLEAN     Found     = FALSE;
 346
 347   if (mObservableDb != NULL) {
 348     //
 349     // Find the observable guid that we're looking for.
 350     //
 351     for (TempTree = mObservableDb; TempTree != NULL; TempTree = TempTree->Next) {
 352       if (CompareMem(&(TempTree->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid)) == 0) {
 353         Found = TRUE;
 354         break;
 355       }
 356     }
 357     if (Found) {
 358       //
 359       // Prepare to add a new leaf.
 360       //
 361       NewLeaf = AllocateZeroPool(sizeof(OBS_LEAF));
 362       if (!NewLeaf) {
 363         Status = EFI_OUT_OF_RESOURCES;
 364       } else {
 365         NewLeaf->Next = NULL;
 366         NewLeaf->Observer = CallbackInterface;
 367         //
 368         // Go to the end of the list of observers.
 369         //
 370         if (TempTree->Leaf != NULL) {
 371           //
 372           // First check to see if this is a duplicate observer.
 373           //
 374           Found = FALSE;
 375           TempLeaf = TempTree->Leaf;
 376           do {
 377             Last = TempLeaf;
 378             if (TempLeaf->Observer == CallbackInterface) {
 379               //
 380               // It is, so let's abort this process.
 381               //
 382               Found = TRUE;
 383               break;
 384             }
 385             TempLeaf = TempLeaf->Next;
 386           } while (TempLeaf != NULL);
 387           TempLeaf = Last;
 388
 389           //
 390           // Check for duplicates.
 391           //
 392           if (Found) {
 393             gBS->FreePool(NewLeaf);
 394             Status = EFI_INVALID_PARAMETER;
 395           } else {
 396             //
 397             // At this point, TempLeaf->Next will be the end of the list.
 398             //
 399             TempLeaf->Next = NewLeaf;
 400           }
 401         } else {
 402           //
 403           // There are no observers listening to this guid. Start a new list.
 404           //
 405           TempTree->Leaf = NewLeaf;
 406         }
 407       }
 408     } else {
 409       Status = EFI_NOT_FOUND;
 410     }
 411   } else {
 412     Status = EFI_NOT_FOUND;
 413   }
 414
 415   return Status;
 416 }
 417
 418 /** Unsubscribe an interface with an observable guid.
 419  *
 420  * Use this to remove an interface from the callback list associated with an observable guid.
 421  *
 422  * @param   EFI_GUID                ReferenceGuid   The observable guid to unsubscribe the interface from.
 423  *          OBS_NOTIFY_INTERFACE    NotifyCallback  A pointer to the interface that is being unsubscribed.
 424  *
 425  * @return  EFI_SUCCESS           Successfully unsubscribed the interface from the observable guid.
 426  **/
 427 EFI_STATUS
 428 EFIAPI
 429 Unsubscribe (
 430   IN      EFI_GUID        ReferenceGuid,
 431   IN      OBS_CALLBACK    CallbackInterface
 432   )
 433 {
 434   mObservableDb = FindAndDeleteSubscriber(mObservableDb, ReferenceGuid, CallbackInterface);
 435
 436   return EFI_SUCCESS;
 437 }
 438
 439 /** Notify observing functions.
 440  *
 441  * Use this to notify all functions who are subscribed to the guid specified by ReferenceGuid.
 442  *
 443  * @param   EFI_GUID          ReferenceGuid   The observable guid that contains the the list of interfaces to be notified.
 444  *          VOID*             Data            Parameter context to be passed to the notification function.
 445  *
 446  * @return  EFI_SUCCESS       Successfully notified all observers listening to this guid.
 447  *          EFI_NOT_FOUND     No match could be found between the provided guid and existing observables.
 448  **/
 449 EFI_STATUS
 450 EFIAPI
 451 Publish (
 452   IN      EFI_GUID                  ReferenceGuid,
 453   IN  OUT VOID*                     Data
 454   )
 455 {
 456   EFI_STATUS  Status    = EFI_SUCCESS;
 457   OBS_TREE*   TempTree  = NULL;
 458   OBS_LEAF*   TempLeaf  = NULL;
 459   BOOLEAN     Found     = FALSE;
 460
 461   if (mObservableDb != NULL) {
 462     //
 463     // Find the observable guid that we're looking for.
 464     //
 465     for (TempTree = mObservableDb; TempTree != NULL; TempTree = TempTree->Next) {
 466       if (CompareMem(&(TempTree->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid)) == 0) {
 467         Found = TRUE;
 468         break;
 469       }
 470     }
 471     if (Found) {
 472       //
 473       // Notify every listener by performing each provided callback.
 474       //
 475       for (TempLeaf = TempTree->Leaf; TempLeaf != NULL; TempLeaf = TempLeaf->Next) {
 476         if (TempLeaf->Observer != NULL) {
 477           //
 478           // Execute the callback.
 479           //
 480           TempLeaf->Observer(Data);
 481         }
 482       }
 483     } else {
 484       Status = EFI_NOT_FOUND;
 485     }
 486   } else {
 487     Status = EFI_NOT_FOUND;
 488   }
 489
 490   return Status;
 491 }
 492
 493 /** Creates a new observable.
 494  *
 495  * Create a new observable that can be observed with the use of Subscribe function.
 496  *
 497  * @param   EFI_GUID              ReferenceGuid   The observable guid to add.
 498  *
 499  * @return  EFI_SUCCESS           Successfully added observable.
 500  *          EFI_INVALID_PARAMETER Observable already exists.
 501  **/
 502 EFI_STATUS
 503 EFIAPI
 504 AddObservable (
 505   IN      EFI_GUID                  ReferenceGuid
 506   )
 507 {
 508   EFI_STATUS  Status    = EFI_SUCCESS;
 509   OBS_TREE*   TempTree  = NULL;
 510   OBS_TREE*   Last      = NULL;
 511   OBS_TREE*   NewTree   = NULL;
 512   BOOLEAN     Found     = FALSE;
 513
 514   if (mObservableDb != NULL) {
 515     if (mObservableDb->Next != NULL) {
 516       //
 517       // Iterate to the end of the observable list while checking to see if we aren't creating a duplicate.
 518       //
 519       TempTree = mObservableDb->Next;
 520       do {
 521         Last = TempTree;
 522         if (CompareMem(&(TempTree->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid)) == 0) {
 523           Found = TRUE;
 524           break;
 525         }
 526         TempTree = TempTree->Next;
 527       } while (TempTree != NULL);
 528       TempTree = Last;
 529     } else {
 530       TempTree = mObservableDb;
 531     }
 532     if (Found) {
 533       //
 534       // Duplicate, so reject the parameter.
 535       //
 536       Status = EFI_INVALID_PARAMETER;
 537     } else {
 538       //
 539       // TempTree->Next is our target. Prepare to add a new tree link.
 540       //
 541       NewTree = AllocateZeroPool(sizeof(OBS_TREE));
 542       if (NewTree) {
 543         NewTree->Next = NULL;
 544         NewTree->Leaf = NULL;
 545         CopyMem(&(NewTree->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid));
 546         TempTree->Next = NewTree;
 547       } else {
 548         Status = EFI_OUT_OF_RESOURCES;
 549       }
 550     }
 551   } else {
 552     //
 553     // mObservableDb has not been created yet. Let's do that.
 554     //
 555     NewTree = AllocateZeroPool(sizeof(OBS_TREE));
 556     if (NewTree) {
 557       NewTree->Next = NULL;
 558       NewTree->Leaf = NULL;
 559       CopyMem(&(NewTree->ObservableGuid), &ReferenceGuid, sizeof(ReferenceGuid));
 560       mObservableDb = NewTree;
 561     } else {
 562       Status = EFI_OUT_OF_RESOURCES;
 563     }
 564   }
 565
 566   return Status;
 567 }
 568
 569 /** Remove an observable.
 570  *
 571  * Remove an observable so that it can no longer be subscribed to. In addition, unsubscribe any functions
 572  * that are subscribed to this guid.
 573  *
 574  * @param   EFI_GUID              ReferenceGuid   The observable guid to remove.
 575  *
 576  * @return  EFI_SUCCESS           Successfully removed observable.
 577  **/
 578 EFI_STATUS
 579 EFIAPI
 580 RemoveObservable (
 581   IN      EFI_GUID        ReferenceGuid
 582   )
 583 {
 584   mObservableDb = FindAndDeleteObservable(mObservableDb, ReferenceGuid);
 585
 586   return EFI_SUCCESS;
 587 }