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