1 /** @file 2 Miscellaneous definitions for iSCSI driver. 3 4 Copyright (c) 2004 - 2016, 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 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 _ISCSI_MISC_H_ 16 #define _ISCSI_MISC_H_ 17 18 typedef struct _ISCSI_DRIVER_DATA ISCSI_DRIVER_DATA; 19 20 /// 21 /// IPv4 Device Path Node Length 22 /// 23 #define IP4_NODE_LEN_NEW_VERSIONS 27 24 25 /// 26 /// IPv6 Device Path Node Length 27 /// 28 #define IP6_NODE_LEN_OLD_VERSIONS 43 29 #define IP6_NODE_LEN_NEW_VERSIONS 60 30 31 /// 32 /// The ignored field StaticIpAddress's offset in old IPv6 Device Path 33 /// 34 #define IP6_OLD_IPADDRESS_OFFSET 42 35 36 #pragma pack(1) 37 typedef struct _ISCSI_SESSION_CONFIG_NVDATA { 38 UINT16 TargetPort; 39 UINT8 Enabled; 40 UINT8 IpMode; 41 42 EFI_IP_ADDRESS LocalIp; 43 EFI_IPv4_ADDRESS SubnetMask; 44 EFI_IP_ADDRESS Gateway; 45 46 BOOLEAN InitiatorInfoFromDhcp; 47 BOOLEAN TargetInfoFromDhcp; 48 CHAR8 TargetName[ISCSI_NAME_MAX_SIZE]; 49 EFI_IP_ADDRESS TargetIp; 50 UINT8 PrefixLength; 51 UINT8 BootLun[8]; 52 53 UINT16 ConnectTimeout; ///< timout value in milliseconds. 54 UINT8 ConnectRetryCount; 55 UINT8 IsId[6]; 56 57 BOOLEAN RedirectFlag; 58 UINT16 OriginalTargetPort; // The port of proxy/virtual target. 59 EFI_IP_ADDRESS OriginalTargetIp; // The address of proxy/virtual target. 60 61 } ISCSI_SESSION_CONFIG_NVDATA; 62 #pragma pack() 63 64 /** 65 Calculate the prefix length of the IPv4 subnet mask. 66 67 @param[in] SubnetMask The IPv4 subnet mask. 68 69 @return The prefix length of the subnet mask. 70 @retval 0 Other errors as indicated. 71 72 **/ 73 UINT8 74 IScsiGetSubnetMaskPrefixLength ( 75 IN EFI_IPv4_ADDRESS *SubnetMask 76 ); 77 78 /** 79 Convert the hexadecimal encoded LUN string into the 64-bit LUN. 80 81 @param[in] Str The hexadecimal encoded LUN string. 82 @param[out] Lun Storage to return the 64-bit LUN. 83 84 @retval EFI_SUCCESS The 64-bit LUN is stored in Lun. 85 @retval EFI_INVALID_PARAMETER The string is malformatted. 86 87 **/ 88 EFI_STATUS 89 IScsiAsciiStrToLun ( 90 IN CHAR8 *Str, 91 OUT UINT8 *Lun 92 ); 93 94 /** 95 Convert the 64-bit LUN into the hexadecimal encoded LUN string. 96 97 @param[in] Lun The 64-bit LUN. 98 @param[out] String The storage to return the hexadecimal encoded LUN string. 99 100 **/ 101 VOID 102 IScsiLunToUnicodeStr ( 103 IN UINT8 *Lun, 104 OUT CHAR16 *String 105 ); 106 107 /** 108 Convert the mac address into a hexadecimal encoded "-" seperated string. 109 110 @param[in] Mac The mac address. 111 @param[in] Len Length in bytes of the mac address. 112 @param[in] VlanId VLAN ID of the network device. 113 @param[out] Str The storage to return the mac string. 114 115 **/ 116 VOID 117 IScsiMacAddrToStr ( 118 IN EFI_MAC_ADDRESS *Mac, 119 IN UINT32 Len, 120 IN UINT16 VlanId, 121 OUT CHAR16 *Str 122 ); 123 124 /** 125 Convert the formatted IP address into the binary IP address. 126 127 @param[in] Str The UNICODE string. 128 @param[in] IpMode Indicates whether the IP address is v4 or v6. 129 @param[out] Ip The storage to return the ASCII string. 130 131 @retval EFI_SUCCESS The binary IP address is returned in Ip. 132 @retval EFI_INVALID_PARAMETER The IP string is malformatted or IpMode is 133 invalid. 134 135 **/ 136 EFI_STATUS 137 IScsiAsciiStrToIp ( 138 IN CHAR8 *Str, 139 IN UINT8 IpMode, 140 OUT EFI_IP_ADDRESS *Ip 141 ); 142 143 /** 144 Convert the binary encoded buffer into a hexadecimal encoded string. 145 146 @param[in] BinBuffer The buffer containing the binary data. 147 @param[in] BinLength Length of the binary buffer. 148 @param[in, out] HexStr Pointer to the string. 149 @param[in, out] HexLength The length of the string. 150 151 @retval EFI_SUCCESS The binary data is converted to the hexadecimal string 152 and the length of the string is updated. 153 @retval EFI_BUFFER_TOO_SMALL The string is too small. 154 @retval EFI_INVALID_PARAMETER The IP string is malformatted. 155 156 **/ 157 EFI_STATUS 158 IScsiBinToHex ( 159 IN UINT8 *BinBuffer, 160 IN UINT32 BinLength, 161 IN OUT CHAR8 *HexStr, 162 IN OUT UINT32 *HexLength 163 ); 164 165 /** 166 Convert the hexadecimal string into a binary encoded buffer. 167 168 @param[in, out] BinBuffer The binary buffer. 169 @param[in, out] BinLength Length of the binary buffer. 170 @param[in] HexStr The hexadecimal string. 171 172 @retval EFI_SUCCESS The hexadecimal string is converted into a binary 173 encoded buffer. 174 @retval EFI_BUFFER_TOO_SMALL The binary buffer is too small to hold the converted data. 175 176 **/ 177 EFI_STATUS 178 IScsiHexToBin ( 179 IN OUT UINT8 *BinBuffer, 180 IN OUT UINT32 *BinLength, 181 IN CHAR8 *HexStr 182 ); 183 184 185 /** 186 Convert the decimal-constant string or hex-constant string into a numerical value. 187 188 @param[in] Str String in decimal or hex. 189 190 @return The numerical value. 191 192 **/ 193 UINTN 194 IScsiNetNtoi ( 195 IN CHAR8 *Str 196 ); 197 198 /** 199 Generate random numbers. 200 201 @param[in, out] Rand The buffer to contain random numbers. 202 @param[in] RandLength The length of the Rand buffer. 203 204 **/ 205 VOID 206 IScsiGenRandom ( 207 IN OUT UINT8 *Rand, 208 IN UINTN RandLength 209 ); 210 211 /** 212 Record the NIC information in a global structure. 213 214 @param[in] Controller The handle of the controller. 215 216 @retval EFI_SUCCESS The operation is completed. 217 @retval EFI_OUT_OF_RESOURCES Do not have sufficient resource to finish this 218 operation. 219 220 **/ 221 EFI_STATUS 222 IScsiAddNic ( 223 IN EFI_HANDLE Controller 224 ); 225 226 /** 227 Delete the recorded NIC information from a global structure. Also delete corresponding 228 attempts. 229 230 @param[in] Controller The handle of the controller. 231 232 @retval EFI_SUCCESS The operation completed. 233 @retval EFI_NOT_FOUND The NIC information to be deleted is not recorded. 234 235 **/ 236 EFI_STATUS 237 IScsiRemoveNic ( 238 IN EFI_HANDLE Controller 239 ); 240 241 /** 242 Get the recorded NIC information from a global structure by the Index. 243 244 @param[in] NicIndex The index indicates the position of NIC info. 245 246 @return Pointer to the NIC info or NULL if not found. 247 248 **/ 249 ISCSI_NIC_INFO * 250 IScsiGetNicInfoByIndex ( 251 IN UINT8 NicIndex 252 ); 253 254 255 /** 256 Get the NIC's PCI location and return it according to the composited 257 format defined in iSCSI Boot Firmware Table. 258 259 @param[in] Controller The handle of the controller. 260 @param[out] Bus The bus number. 261 @param[out] Device The device number. 262 @param[out] Function The function number. 263 264 @return The composited representation of the NIC PCI location. 265 266 **/ 267 UINT16 268 IScsiGetNICPciLocation ( 269 IN EFI_HANDLE Controller, 270 OUT UINTN *Bus, 271 OUT UINTN *Device, 272 OUT UINTN *Function 273 ); 274 275 /** 276 Read the EFI variable (VendorGuid/Name) and return a dynamically allocated 277 buffer, and the size of the buffer. If failure, return NULL. 278 279 @param[in] Name String part of EFI variable name. 280 @param[in] VendorGuid GUID part of EFI variable name. 281 @param[out] VariableSize Returns the size of the EFI variable that was read. 282 283 @return Dynamically allocated memory that contains a copy of the EFI variable. 284 @return Caller is responsible freeing the buffer. 285 @retval NULL Variable was not read. 286 287 **/ 288 VOID * 289 IScsiGetVariableAndSize ( 290 IN CHAR16 *Name, 291 IN EFI_GUID *VendorGuid, 292 OUT UINTN *VariableSize 293 ); 294 295 /** 296 Create the iSCSI driver data. 297 298 @param[in] Image The handle of the driver image. 299 @param[in] Controller The handle of the controller. 300 301 @return The iSCSI driver data created. 302 @retval NULL Other errors as indicated. 303 304 **/ 305 ISCSI_DRIVER_DATA * 306 IScsiCreateDriverData ( 307 IN EFI_HANDLE Image, 308 IN EFI_HANDLE Controller 309 ); 310 311 /** 312 Clean the iSCSI driver data. 313 314 @param[in] Private The iSCSI driver data. 315 316 @retval EFI_SUCCES The clean operation is successful. 317 @retval Others Other errors as indicated. 318 319 **/ 320 EFI_STATUS 321 IScsiCleanDriverData ( 322 IN ISCSI_DRIVER_DATA *Private 323 ); 324 325 /** 326 Check wheather the Controller handle is configured to use DHCP protocol. 327 328 @param[in] Controller The handle of the controller. 329 @param[in] IpVersion IP_VERSION_4 or IP_VERSION_6. 330 331 @retval TRUE The handle of the controller need the Dhcp protocol. 332 @retval FALSE The handle of the controller does not need the Dhcp protocol. 333 334 **/ 335 BOOLEAN 336 IScsiDhcpIsConfigured ( 337 IN EFI_HANDLE Controller, 338 IN UINT8 IpVersion 339 ); 340 341 /** 342 Get the various configuration data of this iSCSI instance. 343 344 @param[in] Private The iSCSI driver data. 345 346 @retval EFI_SUCCESS Obtained the configuration of this instance. 347 @retval EFI_ABORTED The operation was aborted. 348 @retval Others Other errors as indicated. 349 350 **/ 351 EFI_STATUS 352 IScsiGetConfigData ( 353 IN ISCSI_DRIVER_DATA *Private 354 ); 355 356 /** 357 Get the device path of the iSCSI tcp connection and update it. 358 359 @param[in] Session The iSCSI session data. 360 361 @return The updated device path. 362 @retval NULL Other errors as indicated. 363 364 **/ 365 EFI_DEVICE_PATH_PROTOCOL * 366 IScsiGetTcpConnDevicePath ( 367 IN ISCSI_SESSION *Session 368 ); 369 370 /** 371 Abort the session when the transition from BS to RT is initiated. 372 373 @param[in] Event The event signaled. 374 @param[in] Context The iSCSI driver data. 375 376 **/ 377 VOID 378 EFIAPI 379 IScsiOnExitBootService ( 380 IN EFI_EVENT Event, 381 IN VOID *Context 382 ); 383 384 /** 385 Tests whether a controller handle is being managed by IScsi driver. 386 387 This function tests whether the driver specified by DriverBindingHandle is 388 currently managing the controller specified by ControllerHandle. This test 389 is performed by evaluating if the the protocol specified by ProtocolGuid is 390 present on ControllerHandle and is was opened by DriverBindingHandle and Nic 391 Device handle with an attribute of EFI_OPEN_PROTOCOL_BY_DRIVER. 392 If ProtocolGuid is NULL, then ASSERT(). 393 394 @param ControllerHandle A handle for a controller to test. 395 @param DriverBindingHandle Specifies the driver binding handle for the 396 driver. 397 @param ProtocolGuid Specifies the protocol that the driver specified 398 by DriverBindingHandle opens in its Start() 399 function. 400 401 @retval EFI_SUCCESS ControllerHandle is managed by the driver 402 specified by DriverBindingHandle. 403 @retval EFI_UNSUPPORTED ControllerHandle is not managed by the driver 404 specified by DriverBindingHandle. 405 406 **/ 407 EFI_STATUS 408 EFIAPI 409 IScsiTestManagedDevice ( 410 IN EFI_HANDLE ControllerHandle, 411 IN EFI_HANDLE DriverBindingHandle, 412 IN EFI_GUID *ProtocolGuid 413 ); 414 #endif 415