1 /** @file 2 ARP driver header file. 3 4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 5 SPDX-License-Identifier: BSD-2-Clause-Patent 6 7 **/ 8 9 #ifndef _ARP_DRIVER_H_ 10 #define _ARP_DRIVER_H_ 11 12 13 #include <Uefi.h> 14 15 #include <Protocol/Arp.h> 16 #include <Protocol/ManagedNetwork.h> 17 #include <Protocol/ServiceBinding.h> 18 19 #include <Library/DebugLib.h> 20 #include <Library/UefiDriverEntryPoint.h> 21 #include <Library/UefiBootServicesTableLib.h> 22 #include <Library/UefiLib.h> 23 24 25 // 26 // Global variables 27 // 28 extern EFI_DRIVER_BINDING_PROTOCOL gArpDriverBinding; 29 extern EFI_COMPONENT_NAME_PROTOCOL gArpComponentName; 30 extern EFI_COMPONENT_NAME2_PROTOCOL gArpComponentName2; 31 32 // 33 // Function prototypes for the Drivr Binding Protocol 34 // 35 /** 36 Tests to see if this driver supports a given controller. 37 38 If a child device is provided, it further tests to see if this driver supports 39 creating a handle for the specified child device. 40 41 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 42 @param[in] ControllerHandle The handle of the controller to test. This handle 43 must support a protocol interface that supplies 44 an I/O abstraction to the driver. 45 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. 46 This parameter is ignored by device drivers, 47 and is optional for bus drivers. 48 49 @retval EFI_SUCCESS The device specified by ControllerHandle and 50 RemainingDevicePath is supported by the driver 51 specified by This. 52 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and 53 RemainingDevicePath is already being managed 54 by the driver specified by This. 55 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and 56 RemainingDevicePath is already being managed by 57 a different driver or an application that 58 requires exclusive acces. Currently not implemented. 59 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and 60 RemainingDevicePath is not supported by the 61 driver specified by This. 62 63 **/ 64 EFI_STATUS 65 EFIAPI 66 ArpDriverBindingSupported ( 67 IN EFI_DRIVER_BINDING_PROTOCOL *This, 68 IN EFI_HANDLE ControllerHandle, 69 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL 70 ); 71 72 /** 73 Start this driver on ControllerHandle. 74 75 The Start() function is designed to be invoked from the EFI boot service ConnectController(). 76 As a result, much of the error checking on the parameters to Start() has been 77 moved into this common boot service. It is legal to call Start() from other locations, 78 but the following calling restrictions must be followed or the system behavior 79 will not be deterministic. 80 1. ControllerHandle must be a valid EFI_HANDLE. 81 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally 82 aligned EFI_DEVICE_PATH_PROTOCOL. 83 3. Prior to calling Start(), the Supported() function for the driver specified 84 by This must have been called with the same calling parameters, and Supported() 85 must have returned EFI_SUCCESS. 86 87 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 88 @param[in] ControllerHandle The handle of the controller to start. This handle 89 must support a protocol interface that supplies 90 an I/O abstraction to the driver. 91 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. 92 This parameter is ignored by device drivers, 93 and is optional for bus drivers. 94 95 @retval EFI_SUCCESS The device was started. 96 @retval EFI_DEVICE_ERROR The device could not be started due to a device error. 97 Currently not implemented. 98 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of 99 resources. 100 @retval Others The driver failded to start the device. 101 102 **/ 103 EFI_STATUS 104 EFIAPI 105 ArpDriverBindingStart ( 106 IN EFI_DRIVER_BINDING_PROTOCOL *This, 107 IN EFI_HANDLE ControllerHandle, 108 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL 109 ); 110 111 /** 112 Stop this driver on ControllerHandle. 113 114 Release the control of this controller and remove the IScsi functions. The Stop() 115 function is designed to be invoked from the EFI boot service DisconnectController(). 116 As a result, much of the error checking on the parameters to Stop() has been moved 117 into this common boot service. It is legal to call Stop() from other locations, 118 but the following calling restrictions must be followed or the system behavior 119 will not be deterministic. 120 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this 121 same driver's Start() function. 122 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid 123 EFI_HANDLE. In addition, all of these handles must have been created in this driver's 124 Start() function, and the Start() function must have called OpenProtocol() on 125 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. 126 127 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 128 @param[in] ControllerHandle A handle to the device being stopped. The handle must 129 support a bus specific I/O protocol for the driver 130 to use to stop the device. 131 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer. 132 Not used. 133 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL 134 if NumberOfChildren is 0.Not used. 135 136 @retval EFI_SUCCESS The device was stopped. 137 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error. 138 139 **/ 140 EFI_STATUS 141 EFIAPI 142 ArpDriverBindingStop ( 143 IN EFI_DRIVER_BINDING_PROTOCOL *This, 144 IN EFI_HANDLE ControllerHandle, 145 IN UINTN NumberOfChildren, 146 IN EFI_HANDLE *ChildHandleBuffer 147 ); 148 149 /** 150 Creates a child handle and installs a protocol. 151 152 The CreateChild() function installs a protocol on ChildHandle. 153 If ChildHandle is a pointer to NULL, then a new handle is created and returned 154 in ChildHandle. If ChildHandle is not a pointer to NULL, then the protocol 155 installs on the existing ChildHandle. 156 157 @param This Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance. 158 @param ChildHandle Pointer to the handle of the child to create. If it is NULL, 159 then a new handle is created. If it is a pointer to an existing 160 UEFI handle, then the protocol is added to the existing UEFI handle. 161 162 @retval EFI_SUCCES The protocol was added to ChildHandle. 163 @retval EFI_INVALID_PARAMETER ChildHandle is NULL. 164 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to create 165 the child 166 @retval other The child handle was not created 167 168 **/ 169 EFI_STATUS 170 EFIAPI 171 ArpServiceBindingCreateChild ( 172 IN EFI_SERVICE_BINDING_PROTOCOL *This, 173 IN EFI_HANDLE *ChildHandle 174 ); 175 176 /** 177 Destroys a child handle with a protocol installed on it. 178 179 The DestroyChild() function does the opposite of CreateChild(). It removes a protocol 180 that was installed by CreateChild() from ChildHandle. If the removed protocol is the 181 last protocol on ChildHandle, then ChildHandle is destroyed. 182 183 @param This Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance. 184 @param ChildHandle Handle of the child to destroy 185 186 @retval EFI_SUCCES The protocol was removed from ChildHandle. 187 @retval EFI_UNSUPPORTED ChildHandle does not support the protocol that is 188 being removed. 189 @retval EFI_INVALID_PARAMETER Child handle is NULL. 190 @retval EFI_ACCESS_DENIED The protocol could not be removed from the ChildHandle 191 because its services are being used. 192 @retval other The child handle was not destroyed 193 194 **/ 195 EFI_STATUS 196 EFIAPI 197 ArpServiceBindingDestroyChild ( 198 IN EFI_SERVICE_BINDING_PROTOCOL *This, 199 IN EFI_HANDLE ChildHandle 200 ); 201 202 203 // 204 // EFI Component Name Functions 205 // 206 /** 207 Retrieves a Unicode string that is the user readable name of the driver. 208 209 This function retrieves the user readable name of a driver in the form of a 210 Unicode string. If the driver specified by This has a user readable name in 211 the language specified by Language, then a pointer to the driver name is 212 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified 213 by This does not support the language specified by Language, 214 then EFI_UNSUPPORTED is returned. 215 216 @param[in] This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 217 EFI_COMPONENT_NAME_PROTOCOL instance. 218 219 @param[in] Language A pointer to a Null-terminated ASCII string 220 array indicating the language. This is the 221 language of the driver name that the caller is 222 requesting, and it must match one of the 223 languages specified in SupportedLanguages. The 224 number of languages supported by a driver is up 225 to the driver writer. Language is specified 226 in RFC 4646 or ISO 639-2 language code format. 227 228 @param[out] DriverName A pointer to the Unicode string to return. 229 This Unicode string is the name of the 230 driver specified by This in the language 231 specified by Language. 232 233 @retval EFI_SUCCESS The Unicode string for the Driver specified by 234 This and the language specified by Language was 235 returned in DriverName. 236 237 @retval EFI_INVALID_PARAMETER Language is NULL. 238 239 @retval EFI_INVALID_PARAMETER DriverName is NULL. 240 241 @retval EFI_UNSUPPORTED The driver specified by This does not support 242 the language specified by Language. 243 244 **/ 245 EFI_STATUS 246 EFIAPI 247 ArpComponentNameGetDriverName ( 248 IN EFI_COMPONENT_NAME_PROTOCOL *This, 249 IN CHAR8 *Language, 250 OUT CHAR16 **DriverName 251 ); 252 253 254 /** 255 Retrieves a Unicode string that is the user readable name of the controller 256 that is being managed by a driver. 257 258 This function retrieves the user readable name of the controller specified by 259 ControllerHandle and ChildHandle in the form of a Unicode string. If the 260 driver specified by This has a user readable name in the language specified by 261 Language, then a pointer to the controller name is returned in ControllerName, 262 and EFI_SUCCESS is returned. If the driver specified by This is not currently 263 managing the controller specified by ControllerHandle and ChildHandle, 264 then EFI_UNSUPPORTED is returned. If the driver specified by This does not 265 support the language specified by Language, then EFI_UNSUPPORTED is returned. 266 267 @param[in] This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 268 EFI_COMPONENT_NAME_PROTOCOL instance. 269 270 @param[in] ControllerHandle The handle of a controller that the driver 271 specified by This is managing. This handle 272 specifies the controller whose name is to be 273 returned. 274 275 @param[in] ChildHandle The handle of the child controller to retrieve 276 the name of. This is an optional parameter that 277 may be NULL. It will be NULL for device 278 drivers. It will also be NULL for a bus drivers 279 that wish to retrieve the name of the bus 280 controller. It will not be NULL for a bus 281 driver that wishes to retrieve the name of a 282 child controller. 283 284 @param[in] Language A pointer to a Null-terminated ASCII string 285 array indicating the language. This is the 286 language of the driver name that the caller is 287 requesting, and it must match one of the 288 languages specified in SupportedLanguages. The 289 number of languages supported by a driver is up 290 to the driver writer. Language is specified in 291 RFC 4646 or ISO 639-2 language code format. 292 293 @param[out] ControllerName A pointer to the Unicode string to return. 294 This Unicode string is the name of the 295 controller specified by ControllerHandle and 296 ChildHandle in the language specified by 297 Language from the point of view of the driver 298 specified by This. 299 300 @retval EFI_SUCCESS The Unicode string for the user readable name in 301 the language specified by Language for the 302 driver specified by This was returned in 303 DriverName. 304 305 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL. 306 307 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid 308 EFI_HANDLE. 309 310 @retval EFI_INVALID_PARAMETER Language is NULL. 311 312 @retval EFI_INVALID_PARAMETER ControllerName is NULL. 313 314 @retval EFI_UNSUPPORTED The driver specified by This is not currently 315 managing the controller specified by 316 ControllerHandle and ChildHandle. 317 318 @retval EFI_UNSUPPORTED The driver specified by This does not support 319 the language specified by Language. 320 321 **/ 322 EFI_STATUS 323 EFIAPI 324 ArpComponentNameGetControllerName ( 325 IN EFI_COMPONENT_NAME_PROTOCOL *This, 326 IN EFI_HANDLE ControllerHandle, 327 IN EFI_HANDLE ChildHandle OPTIONAL, 328 IN CHAR8 *Language, 329 OUT CHAR16 **ControllerName 330 ); 331 332 333 #endif 334 335