Observable.c 17 KB

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