1*f334afcfSToomas Soome /** @file 2*f334afcfSToomas Soome UEFI DriverBinding Protocol is defined in UEFI specification. 3*f334afcfSToomas Soome 4*f334afcfSToomas Soome This protocol is produced by every driver that follows the UEFI Driver Model, 5*f334afcfSToomas Soome and it is the central component that allows drivers and controllers to be managed. 6*f334afcfSToomas Soome 7*f334afcfSToomas Soome Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 8*f334afcfSToomas Soome SPDX-License-Identifier: BSD-2-Clause-Patent 9*f334afcfSToomas Soome 10*f334afcfSToomas Soome **/ 11*f334afcfSToomas Soome 12*f334afcfSToomas Soome #ifndef __EFI_DRIVER_BINDING_H__ 13*f334afcfSToomas Soome #define __EFI_DRIVER_BINDING_H__ 14*f334afcfSToomas Soome 15*f334afcfSToomas Soome /// 16*f334afcfSToomas Soome /// The global ID for the ControllerHandle Driver Protocol. 17*f334afcfSToomas Soome /// 18*f334afcfSToomas Soome #define EFI_DRIVER_BINDING_PROTOCOL_GUID \ 19*f334afcfSToomas Soome { \ 20*f334afcfSToomas Soome 0x18a031ab, 0xb443, 0x4d1a, {0xa5, 0xc0, 0xc, 0x9, 0x26, 0x1e, 0x9f, 0x71 } \ 21*f334afcfSToomas Soome } 22*f334afcfSToomas Soome 23*f334afcfSToomas Soome typedef struct _EFI_DRIVER_BINDING_PROTOCOL EFI_DRIVER_BINDING_PROTOCOL; 24*f334afcfSToomas Soome 25*f334afcfSToomas Soome /** 26*f334afcfSToomas Soome Tests to see if this driver supports a given controller. If a child device is provided, 27*f334afcfSToomas Soome it further tests to see if this driver supports creating a handle for the specified child device. 28*f334afcfSToomas Soome 29*f334afcfSToomas Soome This function checks to see if the driver specified by This supports the device specified by 30*f334afcfSToomas Soome ControllerHandle. Drivers will typically use the device path attached to 31*f334afcfSToomas Soome ControllerHandle and/or the services from the bus I/O abstraction attached to 32*f334afcfSToomas Soome ControllerHandle to determine if the driver supports ControllerHandle. This function 33*f334afcfSToomas Soome may be called many times during platform initialization. In order to reduce boot times, the tests 34*f334afcfSToomas Soome performed by this function must be very small, and take as little time as possible to execute. This 35*f334afcfSToomas Soome function must not change the state of any hardware devices, and this function must be aware that the 36*f334afcfSToomas Soome device specified by ControllerHandle may already be managed by the same driver or a 37*f334afcfSToomas Soome different driver. This function must match its calls to AllocatePages() with FreePages(), 38*f334afcfSToomas Soome AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol(). 39*f334afcfSToomas Soome Because ControllerHandle may have been previously started by the same driver, if a protocol is 40*f334afcfSToomas Soome already in the opened state, then it must not be closed with CloseProtocol(). This is required 41*f334afcfSToomas Soome to guarantee the state of ControllerHandle is not modified by this function. 42*f334afcfSToomas Soome 43*f334afcfSToomas Soome @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 44*f334afcfSToomas Soome @param[in] ControllerHandle The handle of the controller to test. This handle 45*f334afcfSToomas Soome must support a protocol interface that supplies 46*f334afcfSToomas Soome an I/O abstraction to the driver. 47*f334afcfSToomas Soome @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This 48*f334afcfSToomas Soome parameter is ignored by device drivers, and is optional for bus 49*f334afcfSToomas Soome drivers. For bus drivers, if this parameter is not NULL, then 50*f334afcfSToomas Soome the bus driver must determine if the bus controller specified 51*f334afcfSToomas Soome by ControllerHandle and the child controller specified 52*f334afcfSToomas Soome by RemainingDevicePath are both supported by this 53*f334afcfSToomas Soome bus driver. 54*f334afcfSToomas Soome 55*f334afcfSToomas Soome @retval EFI_SUCCESS The device specified by ControllerHandle and 56*f334afcfSToomas Soome RemainingDevicePath is supported by the driver specified by This. 57*f334afcfSToomas Soome @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and 58*f334afcfSToomas Soome RemainingDevicePath is already being managed by the driver 59*f334afcfSToomas Soome specified by This. 60*f334afcfSToomas Soome @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and 61*f334afcfSToomas Soome RemainingDevicePath is already being managed by a different 62*f334afcfSToomas Soome driver or an application that requires exclusive access. 63*f334afcfSToomas Soome Currently not implemented. 64*f334afcfSToomas Soome @retval EFI_UNSUPPORTED The device specified by ControllerHandle and 65*f334afcfSToomas Soome RemainingDevicePath is not supported by the driver specified by This. 66*f334afcfSToomas Soome **/ 67*f334afcfSToomas Soome typedef 68*f334afcfSToomas Soome EFI_STATUS 69*f334afcfSToomas Soome (EFIAPI *EFI_DRIVER_BINDING_SUPPORTED)( 70*f334afcfSToomas Soome IN EFI_DRIVER_BINDING_PROTOCOL *This, 71*f334afcfSToomas Soome IN EFI_HANDLE ControllerHandle, 72*f334afcfSToomas Soome IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL 73*f334afcfSToomas Soome ); 74*f334afcfSToomas Soome 75*f334afcfSToomas Soome /** 76*f334afcfSToomas Soome Starts a device controller or a bus controller. 77*f334afcfSToomas Soome 78*f334afcfSToomas Soome The Start() function is designed to be invoked from the EFI boot service ConnectController(). 79*f334afcfSToomas Soome As a result, much of the error checking on the parameters to Start() has been moved into this 80*f334afcfSToomas Soome common boot service. It is legal to call Start() from other locations, 81*f334afcfSToomas Soome but the following calling restrictions must be followed, or the system behavior will not be deterministic. 82*f334afcfSToomas Soome 1. ControllerHandle must be a valid EFI_HANDLE. 83*f334afcfSToomas Soome 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned 84*f334afcfSToomas Soome EFI_DEVICE_PATH_PROTOCOL. 85*f334afcfSToomas Soome 3. Prior to calling Start(), the Supported() function for the driver specified by This must 86*f334afcfSToomas Soome have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS. 87*f334afcfSToomas Soome 88*f334afcfSToomas Soome @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 89*f334afcfSToomas Soome @param[in] ControllerHandle The handle of the controller to start. This handle 90*f334afcfSToomas Soome must support a protocol interface that supplies 91*f334afcfSToomas Soome an I/O abstraction to the driver. 92*f334afcfSToomas Soome @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This 93*f334afcfSToomas Soome parameter is ignored by device drivers, and is optional for bus 94*f334afcfSToomas Soome drivers. For a bus driver, if this parameter is NULL, then handles 95*f334afcfSToomas Soome for all the children of Controller are created by this driver. 96*f334afcfSToomas Soome If this parameter is not NULL and the first Device Path Node is 97*f334afcfSToomas Soome not the End of Device Path Node, then only the handle for the 98*f334afcfSToomas Soome child device specified by the first Device Path Node of 99*f334afcfSToomas Soome RemainingDevicePath is created by this driver. 100*f334afcfSToomas Soome If the first Device Path Node of RemainingDevicePath is 101*f334afcfSToomas Soome the End of Device Path Node, no child handle is created by this 102*f334afcfSToomas Soome driver. 103*f334afcfSToomas Soome 104*f334afcfSToomas Soome @retval EFI_SUCCESS The device was started. 105*f334afcfSToomas Soome @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented. 106*f334afcfSToomas Soome @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 107*f334afcfSToomas Soome @retval Others The driver failded to start the device. 108*f334afcfSToomas Soome 109*f334afcfSToomas Soome **/ 110*f334afcfSToomas Soome typedef 111*f334afcfSToomas Soome EFI_STATUS 112*f334afcfSToomas Soome (EFIAPI *EFI_DRIVER_BINDING_START)( 113*f334afcfSToomas Soome IN EFI_DRIVER_BINDING_PROTOCOL *This, 114*f334afcfSToomas Soome IN EFI_HANDLE ControllerHandle, 115*f334afcfSToomas Soome IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL 116*f334afcfSToomas Soome ); 117*f334afcfSToomas Soome 118*f334afcfSToomas Soome /** 119*f334afcfSToomas Soome Stops a device controller or a bus controller. 120*f334afcfSToomas Soome 121*f334afcfSToomas Soome The Stop() function is designed to be invoked from the EFI boot service DisconnectController(). 122*f334afcfSToomas Soome As a result, much of the error checking on the parameters to Stop() has been moved 123*f334afcfSToomas Soome into this common boot service. It is legal to call Stop() from other locations, 124*f334afcfSToomas Soome but the following calling restrictions must be followed, or the system behavior will not be deterministic. 125*f334afcfSToomas Soome 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this 126*f334afcfSToomas Soome same driver's Start() function. 127*f334afcfSToomas Soome 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid 128*f334afcfSToomas Soome EFI_HANDLE. In addition, all of these handles must have been created in this driver's 129*f334afcfSToomas Soome Start() function, and the Start() function must have called OpenProtocol() on 130*f334afcfSToomas Soome ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. 131*f334afcfSToomas Soome 132*f334afcfSToomas Soome @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 133*f334afcfSToomas Soome @param[in] ControllerHandle A handle to the device being stopped. The handle must 134*f334afcfSToomas Soome support a bus specific I/O protocol for the driver 135*f334afcfSToomas Soome to use to stop the device. 136*f334afcfSToomas Soome @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer. 137*f334afcfSToomas Soome @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL 138*f334afcfSToomas Soome if NumberOfChildren is 0. 139*f334afcfSToomas Soome 140*f334afcfSToomas Soome @retval EFI_SUCCESS The device was stopped. 141*f334afcfSToomas Soome @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error. 142*f334afcfSToomas Soome 143*f334afcfSToomas Soome **/ 144*f334afcfSToomas Soome typedef 145*f334afcfSToomas Soome EFI_STATUS 146*f334afcfSToomas Soome (EFIAPI *EFI_DRIVER_BINDING_STOP)( 147*f334afcfSToomas Soome IN EFI_DRIVER_BINDING_PROTOCOL *This, 148*f334afcfSToomas Soome IN EFI_HANDLE ControllerHandle, 149*f334afcfSToomas Soome IN UINTN NumberOfChildren, 150*f334afcfSToomas Soome IN EFI_HANDLE *ChildHandleBuffer OPTIONAL 151*f334afcfSToomas Soome ); 152*f334afcfSToomas Soome 153*f334afcfSToomas Soome /// 154*f334afcfSToomas Soome /// This protocol provides the services required to determine if a driver supports a given controller. 155*f334afcfSToomas Soome /// If a controller is supported, then it also provides routines to start and stop the controller. 156*f334afcfSToomas Soome /// 157*f334afcfSToomas Soome struct _EFI_DRIVER_BINDING_PROTOCOL { 158*f334afcfSToomas Soome EFI_DRIVER_BINDING_SUPPORTED Supported; 159*f334afcfSToomas Soome EFI_DRIVER_BINDING_START Start; 160*f334afcfSToomas Soome EFI_DRIVER_BINDING_STOP Stop; 161*f334afcfSToomas Soome 162*f334afcfSToomas Soome /// 163*f334afcfSToomas Soome /// The version number of the UEFI driver that produced the 164*f334afcfSToomas Soome /// EFI_DRIVER_BINDING_PROTOCOL. This field is used by 165*f334afcfSToomas Soome /// the EFI boot service ConnectController() to determine 166*f334afcfSToomas Soome /// the order that driver's Supported() service will be used when 167*f334afcfSToomas Soome /// a controller needs to be started. EFI Driver Binding Protocol 168*f334afcfSToomas Soome /// instances with higher Version values will be used before ones 169*f334afcfSToomas Soome /// with lower Version values. The Version values of 0x0- 170*f334afcfSToomas Soome /// 0x0f and 0xfffffff0-0xffffffff are reserved for 171*f334afcfSToomas Soome /// platform/OEM specific drivers. The Version values of 0x10- 172*f334afcfSToomas Soome /// 0xffffffef are reserved for IHV-developed drivers. 173*f334afcfSToomas Soome /// 174*f334afcfSToomas Soome UINT32 Version; 175*f334afcfSToomas Soome 176*f334afcfSToomas Soome /// 177*f334afcfSToomas Soome /// The image handle of the UEFI driver that produced this instance 178*f334afcfSToomas Soome /// of the EFI_DRIVER_BINDING_PROTOCOL. 179*f334afcfSToomas Soome /// 180*f334afcfSToomas Soome EFI_HANDLE ImageHandle; 181*f334afcfSToomas Soome 182*f334afcfSToomas Soome /// 183*f334afcfSToomas Soome /// The handle on which this instance of the 184*f334afcfSToomas Soome /// EFI_DRIVER_BINDING_PROTOCOL is installed. In most 185*f334afcfSToomas Soome /// cases, this is the same handle as ImageHandle. However, for 186*f334afcfSToomas Soome /// UEFI drivers that produce more than one instance of the 187*f334afcfSToomas Soome /// EFI_DRIVER_BINDING_PROTOCOL, this value may not be 188*f334afcfSToomas Soome /// the same as ImageHandle. 189*f334afcfSToomas Soome /// 190*f334afcfSToomas Soome EFI_HANDLE DriverBindingHandle; 191*f334afcfSToomas Soome }; 192*f334afcfSToomas Soome 193*f334afcfSToomas Soome extern EFI_GUID gEfiDriverBindingProtocolGuid; 194*f334afcfSToomas Soome 195*f334afcfSToomas Soome #endif 196