/** @file\r
- Copyright (c) 2006, Intel Corporation \r
- All rights reserved. This program and the accompanying materials \r
- are licensed and made available under the terms and conditions of the BSD License \r
- which accompanies this distribution. The full text of the license may be found at \r
- http://opensource.org/licenses/bsd-license.php \r
+ UEFI Service Binding Protocol is defined in UEFI specification.\r
\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
+ The file defines the generic Service Binding Protocol functions.\r
+ It provides services that are required to create and destroy child\r
+ handles that support a given set of protocols.\r
\r
- Module Name: ServiceBinding.h\r
+ Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
+ SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __EFI_SERVICE_BINDING_H__\r
#define __EFI_SERVICE_BINDING_H__\r
\r
-//\r
-// Forward reference for pure ANSI compatability\r
-//\r
+///\r
+/// Forward reference for pure ANSI compatability\r
+///\r
typedef struct _EFI_SERVICE_BINDING_PROTOCOL EFI_SERVICE_BINDING_PROTOCOL;\r
\r
/**\r
- Creates a child handle with a set of I/O services.\r
+ Creates a child handle and installs a protocol.\r
\r
- @param This Protocol instance pointer.\r
- @param ChildHandle Pointer to the handle of the child to create. If it is NULL,\r
- then a new handle is created. If it is not NULL, then the\r
- I/O services are added to the existing child handle.\r
+ The CreateChild() function installs a protocol on ChildHandle.\r
+ If ChildHandle is a pointer to NULL, then a new handle is created and returned in ChildHandle.\r
+ If ChildHandle is not a pointer to NULL, then the protocol installs on the existing ChildHandle.\r
\r
- @retval EFI_SUCCES The child handle was created with the I/O services\r
+ @param This Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.\r
+ @param ChildHandle Pointer to the handle of the child to create. If it is NULL,\r
+ then a new handle is created. If it is a pointer to an existing UEFI handle,\r
+ then the protocol is added to the existing UEFI handle.\r
+\r
+ @retval EFI_SUCCES The protocol was added to ChildHandle.\r
@retval EFI_INVALID_PARAMETER ChildHandle is NULL.\r
- @retval EFI_OUT_OF_RESOURCES There are not enough resources availabe to create\r
+ @retval EFI_OUT_OF_RESOURCES There are not enough resources available to create\r
the child\r
@retval other The child handle was not created\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_SERVICE_BINDING_CREATE_CHILD) (\r
+(EFIAPI *EFI_SERVICE_BINDING_CREATE_CHILD)(\r
IN EFI_SERVICE_BINDING_PROTOCOL *This,\r
IN OUT EFI_HANDLE *ChildHandle\r
- )\r
-;\r
+ );\r
\r
/**\r
- Destroys a child handle with a set of I/O services.\r
+ Destroys a child handle with a protocol installed on it.\r
+\r
+ The DestroyChild() function does the opposite of CreateChild(). It removes a protocol\r
+ that was installed by CreateChild() from ChildHandle. If the removed protocol is the\r
+ last protocol on ChildHandle, then ChildHandle is destroyed.\r
\r
- @param This Protocol instance pointer.\r
+ @param This Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.\r
@param ChildHandle Handle of the child to destroy\r
\r
- @retval EFI_SUCCES The I/O services were removed from the child handle\r
- @retval EFI_UNSUPPORTED The child handle does not support the I/O services\r
- that are being removed.\r
- @retval EFI_INVALID_PARAMETER Child handle is not a valid EFI Handle.\r
- @retval EFI_ACCESS_DENIED The child handle could not be destroyed because its\r
- I/O services are being used.\r
+ @retval EFI_SUCCES The protocol was removed from ChildHandle.\r
+ @retval EFI_UNSUPPORTED ChildHandle does not support the protocol that is being removed.\r
+ @retval EFI_INVALID_PARAMETER Child handle is NULL.\r
+ @retval EFI_ACCESS_DENIED The protocol could not be removed from the ChildHandle\r
+ because its services are being used.\r
@retval other The child handle was not destroyed\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_SERVICE_BINDING_DESTROY_CHILD) (\r
+(EFIAPI *EFI_SERVICE_BINDING_DESTROY_CHILD)(\r
IN EFI_SERVICE_BINDING_PROTOCOL *This,\r
IN EFI_HANDLE ChildHandle\r
- )\r
-;\r
+ );\r
\r
+///\r
+/// The EFI_SERVICE_BINDING_PROTOCOL provides member functions to create and destroy\r
+/// child handles. A driver is responsible for adding protocols to the child handle\r
+/// in CreateChild() and removing protocols in DestroyChild(). It is also required\r
+/// that the CreateChild() function opens the parent protocol BY_CHILD_CONTROLLER\r
+/// to establish the parent-child relationship, and closes the protocol in DestroyChild().\r
+/// The pseudo code for CreateChild() and DestroyChild() is provided to specify the\r
+/// required behavior, not to specify the required implementation. Each consumer of\r
+/// a software protocol is responsible for calling CreateChild() when it requires the\r
+/// protocol and calling DestroyChild() when it is finished with that protocol.\r
+///\r
struct _EFI_SERVICE_BINDING_PROTOCOL {\r
EFI_SERVICE_BINDING_CREATE_CHILD CreateChild;\r
EFI_SERVICE_BINDING_DESTROY_CHILD DestroyChild;\r
projects / mirror_edk2.git / blobdiff