MdePkg/Include/Protocol/ServiceBinding.h

   1 /** @file
   2   UEFI Service Binding Protocol is defined in UEFI specification.
   3
   4   The file defines the generic Service Binding Protocol functions.
   5   It provides services that are required to create and destroy child
   6   handles that support a given set of protocols.
   7
   8   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   9   SPDX-License-Identifier: BSD-2-Clause-Patent
  10
  11 **/
  12
  13 #ifndef __EFI_SERVICE_BINDING_H__
  14 #define __EFI_SERVICE_BINDING_H__
  15
  16 ///
  17 /// Forward reference for pure ANSI compatability
  18 ///
  19 typedef struct _EFI_SERVICE_BINDING_PROTOCOL EFI_SERVICE_BINDING_PROTOCOL;
  20
  21 /**
  22   Creates a child handle and installs a protocol.
  23
  24   The CreateChild() function installs a protocol on ChildHandle.
  25   If ChildHandle is a pointer to NULL, then a new handle is created and returned in ChildHandle.
  26   If ChildHandle is not a pointer to NULL, then the protocol installs on the existing ChildHandle.
  27
  28   @param  This        Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
  29   @param  ChildHandle Pointer to the handle of the child to create. If it is NULL,
  30                       then a new handle is created. If it is a pointer to an existing UEFI handle,
  31                       then the protocol is added to the existing UEFI handle.
  32
  33   @retval EFI_SUCCES            The protocol was added to ChildHandle.
  34   @retval EFI_INVALID_PARAMETER ChildHandle is NULL.
  35   @retval EFI_OUT_OF_RESOURCES  There are not enough resources available to create
  36                                 the child
  37   @retval other                 The child handle was not created
  38
  39 **/
  40 typedef
  41 EFI_STATUS
  42 (EFIAPI *EFI_SERVICE_BINDING_CREATE_CHILD)(
  43   IN     EFI_SERVICE_BINDING_PROTOCOL  *This,
  44   IN OUT EFI_HANDLE                    *ChildHandle
  45   );
  46
  47 /**
  48   Destroys a child handle with a protocol installed on it.
  49
  50   The DestroyChild() function does the opposite of CreateChild(). It removes a protocol
  51   that was installed by CreateChild() from ChildHandle. If the removed protocol is the
  52   last protocol on ChildHandle, then ChildHandle is destroyed.
  53
  54   @param  This        Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
  55   @param  ChildHandle Handle of the child to destroy
  56
  57   @retval EFI_SUCCES            The protocol was removed from ChildHandle.
  58   @retval EFI_UNSUPPORTED       ChildHandle does not support the protocol that is being removed.
  59   @retval EFI_INVALID_PARAMETER Child handle is NULL.
  60   @retval EFI_ACCESS_DENIED     The protocol could not be removed from the ChildHandle
  61                                 because its services are being used.
  62   @retval other                 The child handle was not destroyed
  63
  64 **/
  65 typedef
  66 EFI_STATUS
  67 (EFIAPI *EFI_SERVICE_BINDING_DESTROY_CHILD)(
  68   IN EFI_SERVICE_BINDING_PROTOCOL          *This,
  69   IN EFI_HANDLE                            ChildHandle
  70   );
  71
  72 ///
  73 /// The EFI_SERVICE_BINDING_PROTOCOL provides member functions to create and destroy
  74 /// child handles. A driver is responsible for adding protocols to the child handle
  75 /// in CreateChild() and removing protocols in DestroyChild(). It is also required
  76 /// that the CreateChild() function opens the parent protocol BY_CHILD_CONTROLLER
  77 /// to establish the parent-child relationship, and closes the protocol in DestroyChild().
  78 /// The pseudo code for CreateChild() and DestroyChild() is provided to specify the
  79 /// required behavior, not to specify the required implementation. Each consumer of
  80 /// a software protocol is responsible for calling CreateChild() when it requires the
  81 /// protocol and calling DestroyChild() when it is finished with that protocol.
  82 ///
  83 struct _EFI_SERVICE_BINDING_PROTOCOL {
  84   EFI_SERVICE_BINDING_CREATE_CHILD         CreateChild;
  85   EFI_SERVICE_BINDING_DESTROY_CHILD        DestroyChild;
  86 };
  87
  88 #endif