NetworkPkg/Mtftp6Dxe/Mtftp6Support.h

   1 /** @file
   2   Mtftp6 support functions declaration.
   3
   4   Copyright (c) 2009 - 2018, 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] BlockCounter           The continuous block counter instead of the value after roll-over.
 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                *BlockCounter
 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