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