1 /** @file 2 Mtftp6 support functions declaration. 3 4 Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> 5 6 This program and the accompanying materials 7 are licensed and made available under the terms and conditions of the BSD License 8 which accompanies this distribution. The full text of the license may be found at 9 http://opensource.org/licenses/bsd-license.php. 10 11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 13 14 **/ 15 16 #ifndef __EFI_MTFTP6_SUPPORT_H__ 17 #define __EFI_MTFTP6_SUPPORT_H__ 18 19 // 20 // The structure representing a range of block numbers, [Start, End]. 21 // It is used to remember the holes in the MTFTP block space. If all 22 // the holes are filled in, then the download or upload has completed. 23 // 24 typedef struct { 25 LIST_ENTRY Link; 26 INTN Start; 27 INTN End; 28 INTN Round; 29 INTN Bound; 30 } MTFTP6_BLOCK_RANGE; 31 32 33 /** 34 Initialize the block range for either RRQ or WRQ. RRQ and WRQ have 35 different requirements for Start and End. For example, during startup, 36 WRQ initializes its whole valid block range to [0, 0xffff]. This 37 is because the server will send an ACK0 to inform the user to start the 38 upload. When the client receives an ACK0, it will remove 0 from the range, 39 get the next block number, which is 1, then upload the BLOCK1. For RRQ 40 without option negotiation, the server will directly send us the BLOCK1 41 in response to the client's RRQ. When BLOCK1 is received, the client will 42 remove it from the block range and send an ACK. It also works if there 43 is option negotiation. 44 45 @param[in] Head The block range head to initialize. 46 @param[in] Start The Start block number. 47 @param[in] End The last block number. 48 49 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory for initial block range. 50 @retval EFI_SUCCESS The initial block range is created. 51 52 **/ 53 EFI_STATUS 54 Mtftp6InitBlockRange ( 55 IN LIST_ENTRY *Head, 56 IN UINT16 Start, 57 IN UINT16 End 58 ); 59 60 61 /** 62 Get the first valid block number on the range list. 63 64 @param[in] Head The block range head. 65 66 @retval ==-1 If the block range is empty. 67 @retval >-1 The first valid block number. 68 69 **/ 70 INTN 71 Mtftp6GetNextBlockNum ( 72 IN LIST_ENTRY *Head 73 ); 74 75 76 /** 77 Set the last block number of the block range list. It 78 removes all the blocks after the Last. MTFTP initialize the 79 block range to the maximum possible range, such as [0, 0xffff] 80 for WRQ. When it gets the last block number, it calls 81 this function to set the last block number. 82 83 @param[in] Head The block range list. 84 @param[in] Last The last block number. 85 86 **/ 87 VOID 88 Mtftp6SetLastBlockNum ( 89 IN LIST_ENTRY *Head, 90 IN UINT16 Last 91 ); 92 93 94 /** 95 Remove the block number from the block range list. 96 97 @param[in] Head The block range list to remove from. 98 @param[in] Num The block number to remove. 99 @param[in] Completed Whether Num is the last block number 100 @param[out] TotalBlock The continuous block number in all 101 102 @retval EFI_NOT_FOUND The block number isn't in the block range list. 103 @retval EFI_SUCCESS The block number has been removed from the list. 104 @retval EFI_OUT_OF_RESOURCES Failed to allocate resources. 105 106 **/ 107 EFI_STATUS 108 Mtftp6RemoveBlockNum ( 109 IN LIST_ENTRY *Head, 110 IN UINT16 Num, 111 IN BOOLEAN Completed, 112 OUT UINT64 *TotalBlock 113 ); 114 115 116 /** 117 Build and transmit the request packet for the Mtftp6 instance. 118 119 @param[in] Instance The pointer to the Mtftp6 instance. 120 @param[in] Operation The operation code of this packet. 121 122 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory for the request. 123 @retval EFI_SUCCESS The request was built and sent. 124 @retval Others Failed to transmit the packet. 125 126 **/ 127 EFI_STATUS 128 Mtftp6SendRequest ( 129 IN MTFTP6_INSTANCE *Instance, 130 IN UINT16 Operation 131 ); 132 133 134 /** 135 Build and send an error packet. 136 137 @param[in] Instance The pointer to the Mtftp6 instance. 138 @param[in] ErrCode The error code in the packet. 139 @param[in] ErrInfo The error message in the packet. 140 141 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory for the error packet. 142 @retval EFI_SUCCESS The error packet was transmitted. 143 @retval Others Failed to transmit the packet. 144 145 **/ 146 EFI_STATUS 147 Mtftp6SendError ( 148 IN MTFTP6_INSTANCE *Instance, 149 IN UINT16 ErrCode, 150 IN UINT8* ErrInfo 151 ); 152 153 154 /** 155 Send the packet for the Mtftp6 instance. 156 157 @param[in] Instance The pointer to the Mtftp6 instance. 158 @param[in] Packet The pointer to the packet to be sent. 159 160 @retval EFI_SUCCESS The packet was sent out 161 @retval Others Failed to transmit the packet. 162 163 **/ 164 EFI_STATUS 165 Mtftp6TransmitPacket ( 166 IN MTFTP6_INSTANCE *Instance, 167 IN NET_BUF *Packet 168 ); 169 170 171 /** 172 Check packet for GetInfo callback routine. 173 174 @param[in] This The pointer to the Mtftp6 protocol. 175 @param[in] Token The pointer to the Mtftp6 token. 176 @param[in] PacketLen The length of the packet 177 @param[in] Packet The pointer to the received packet. 178 179 @retval EFI_SUCCESS The check process passed successfully. 180 @retval EFI_ABORTED Abort the Mtftp6 operation. 181 182 **/ 183 EFI_STATUS 184 EFIAPI 185 Mtftp6CheckPacket ( 186 IN EFI_MTFTP6_PROTOCOL *This, 187 IN EFI_MTFTP6_TOKEN *Token, 188 IN UINT16 PacketLen, 189 IN EFI_MTFTP6_PACKET *Packet 190 ); 191 192 193 /** 194 The dummy configure routine for create a new Udp6 Io. 195 196 @param[in] UdpIo The pointer to the Udp6 Io. 197 @param[in] Context The pointer to the context. 198 199 @retval EFI_SUCCESS The value is always returned. 200 201 **/ 202 EFI_STATUS 203 EFIAPI 204 Mtftp6ConfigDummyUdpIo ( 205 IN UDP_IO *UdpIo, 206 IN VOID *Context 207 ); 208 209 210 /** 211 The configure routine for the Mtftp6 instance to transmit/receive. 212 213 @param[in] UdpIo The pointer to the Udp6 Io. 214 @param[in] ServerIp The pointer to the server address. 215 @param[in] ServerPort The pointer to the server port. 216 @param[in] LocalIp The pointer to the local address. 217 @param[in] LocalPort The pointer to the local port. 218 219 @retval EFI_SUCCESS Configure the Udp6 Io for Mtftp6 successfully. 220 @retval EFI_NO_MAPPING The corresponding Ip6 instance has not been 221 configured yet. 222 223 **/ 224 EFI_STATUS 225 Mtftp6ConfigUdpIo ( 226 IN UDP_IO *UdpIo, 227 IN EFI_IPv6_ADDRESS *ServerIp, 228 IN UINT16 ServerPort, 229 IN EFI_IPv6_ADDRESS *LocalIp, 230 IN UINT16 LocalPort 231 ); 232 233 234 /** 235 Clean up the current Mtftp6 operation. 236 237 @param[in] Instance The pointer to the Mtftp6 instance. 238 @param[in] Result The result to be returned to the user. 239 240 **/ 241 VOID 242 Mtftp6OperationClean ( 243 IN MTFTP6_INSTANCE *Instance, 244 IN EFI_STATUS Result 245 ); 246 247 248 /** 249 Start the Mtftp6 instance to perform the operation, such as read file, 250 write file, and read directory. 251 252 @param[in] This The MTFTP session 253 @param[in] Token The token that encapsulates the user's request. 254 @param[in] OpCode The operation to perform. 255 256 @retval EFI_INVALID_PARAMETER Some of the parameters are invalid. 257 @retval EFI_NOT_STARTED The MTFTP session hasn't been configured. 258 @retval EFI_ALREADY_STARTED There is pending operation for the session. 259 @retval EFI_SUCCESS The operation was successfully started. 260 261 **/ 262 EFI_STATUS 263 Mtftp6OperationStart ( 264 IN EFI_MTFTP6_PROTOCOL *This, 265 IN EFI_MTFTP6_TOKEN *Token, 266 IN UINT16 OpCode 267 ); 268 269 270 /** 271 The timer ticking routine for the Mtftp6 instance. 272 273 @param[in] Event The pointer to the ticking event. 274 @param[in] Context The pointer to the context. 275 276 **/ 277 VOID 278 EFIAPI 279 Mtftp6OnTimerTick ( 280 IN EFI_EVENT Event, 281 IN VOID *Context 282 ); 283 284 285 /** 286 The packet process callback for Mtftp6 upload. 287 288 @param[in] UdpPacket The pointer to the packet received. 289 @param[in] UdpEpt The pointer to the Udp6 access point. 290 @param[in] IoStatus The status from the Udp6 instance. 291 @param[in] Context The pointer to the context. 292 293 **/ 294 VOID 295 EFIAPI 296 Mtftp6WrqInput ( 297 IN NET_BUF *UdpPacket, 298 IN UDP_END_POINT *UdpEpt, 299 IN EFI_STATUS IoStatus, 300 IN VOID *Context 301 ); 302 303 304 /** 305 Start the Mtftp6 instance to upload. It will first init some states, 306 then send the WRQ request packet, and start to receive the packet. 307 308 @param[in] Instance The pointer to the Mtftp6 instance. 309 @param[in] Operation The operation code of current packet. 310 311 @retval EFI_SUCCESS The Mtftp6 was started to upload. 312 @retval Others Failed to start to upload. 313 314 **/ 315 EFI_STATUS 316 Mtftp6WrqStart ( 317 IN MTFTP6_INSTANCE *Instance, 318 IN UINT16 Operation 319 ); 320 321 322 /** 323 The packet process callback for Mtftp6 download. 324 325 @param[in] UdpPacket The pointer to the packet received. 326 @param[in] UdpEpt The pointer to the Udp6 access point. 327 @param[in] IoStatus The status from Udp6 instance. 328 @param[in] Context The pointer to the context. 329 330 **/ 331 VOID 332 EFIAPI 333 Mtftp6RrqInput ( 334 IN NET_BUF *UdpPacket, 335 IN UDP_END_POINT *UdpEpt, 336 IN EFI_STATUS IoStatus, 337 IN VOID *Context 338 ); 339 340 341 /** 342 Start the Mtftp6 instance to download. It first initializes some 343 of the internal states then builds and sends an RRQ reqeuest packet. 344 Finally, it starts receive for the downloading. 345 346 @param[in] Instance The pointer to the Mtftp6 instance. 347 @param[in] Operation The operation code of current packet. 348 349 @retval EFI_SUCCESS The Mtftp6 was started to download. 350 @retval Others Failed to start to download. 351 352 **/ 353 EFI_STATUS 354 Mtftp6RrqStart ( 355 IN MTFTP6_INSTANCE *Instance, 356 IN UINT16 Operation 357 ); 358 359 #endif 360