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