NetworkPkg/IScsiDxe/IScsiMisc.h

   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 } 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   @retval EFI_SUCCES      The clean operation is successful.
 312   @retval Others          Other errors as indicated.
 313
 314 **/
 315 EFI_STATUS
 316 IScsiCleanDriverData (
 317   IN ISCSI_DRIVER_DATA  *Private
 318   );
 319
 320 /**
 321   Check wheather the Controller handle is configured to use DHCP protocol.
 322
 323   @param[in]  Controller           The handle of the controller.
 324   @param[in]  IpVersion            IP_VERSION_4 or IP_VERSION_6.
 325
 326   @retval TRUE                     The handle of the controller need the Dhcp protocol.
 327   @retval FALSE                    The handle of the controller does not need the Dhcp protocol.
 328
 329 **/
 330 BOOLEAN
 331 IScsiDhcpIsConfigured (
 332   IN EFI_HANDLE  Controller,
 333   IN UINT8       IpVersion
 334   );
 335
 336 /**
 337   Get the various configuration data of this iSCSI instance.
 338
 339   @param[in]  Private   The iSCSI driver data.
 340
 341   @retval EFI_SUCCESS   Obtained the configuration of this instance.
 342   @retval EFI_ABORTED   The operation was aborted.
 343   @retval Others        Other errors as indicated.
 344
 345 **/
 346 EFI_STATUS
 347 IScsiGetConfigData (
 348   IN ISCSI_DRIVER_DATA  *Private
 349   );
 350
 351 /**
 352   Get the device path of the iSCSI tcp connection and update it.
 353
 354   @param[in]  Session The iSCSI session data.
 355
 356   @return The updated device path.
 357   @retval NULL Other errors as indicated.
 358
 359 **/
 360 EFI_DEVICE_PATH_PROTOCOL *
 361 IScsiGetTcpConnDevicePath (
 362   IN ISCSI_SESSION      *Session
 363   );
 364
 365 /**
 366   Abort the session when the transition from BS to RT is initiated.
 367
 368   @param[in]   Event  The event signaled.
 369   @param[in]  Context The iSCSI driver data.
 370
 371 **/
 372 VOID
 373 EFIAPI
 374 IScsiOnExitBootService (
 375   IN EFI_EVENT  Event,
 376   IN VOID       *Context
 377   );
 378
 379 /**
 380   Tests whether a controller handle is being managed by IScsi driver.
 381
 382   This function tests whether the driver specified by DriverBindingHandle is
 383   currently managing the controller specified by ControllerHandle.  This test
 384   is performed by evaluating if the the protocol specified by ProtocolGuid is
 385   present on ControllerHandle and is was opened by DriverBindingHandle and Nic
 386   Device handle with an attribute of EFI_OPEN_PROTOCOL_BY_DRIVER.
 387   If ProtocolGuid is NULL, then ASSERT().
 388
 389   @param  ControllerHandle     A handle for a controller to test.
 390   @param  DriverBindingHandle  Specifies the driver binding handle for the
 391                                driver.
 392   @param  ProtocolGuid         Specifies the protocol that the driver specified
 393                                by DriverBindingHandle opens in its Start()
 394                                function.
 395
 396   @retval EFI_SUCCESS          ControllerHandle is managed by the driver
 397                                specified by DriverBindingHandle.
 398   @retval EFI_UNSUPPORTED      ControllerHandle is not managed by the driver
 399                                specified by DriverBindingHandle.
 400
 401 **/
 402 EFI_STATUS
 403 EFIAPI
 404 IScsiTestManagedDevice (
 405   IN  EFI_HANDLE       ControllerHandle,
 406   IN  EFI_HANDLE       DriverBindingHandle,
 407   IN  EFI_GUID         *ProtocolGuid
 408   );
 409 #endif