NetworkPkg/IScsiDxe/IScsiMisc.h

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