NetworkPkg/IScsiDxe/IScsiMisc.h

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