NetworkPkg/IScsiDxe/IScsiMisc.h

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