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