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