NetworkPkg/Mtftp4Dxe/Mtftp4Support.h

   1 /** @file
   2   Support routines for MTFTP.
   3
   4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef __EFI_MTFTP4_SUPPORT_H__
  10 #define __EFI_MTFTP4_SUPPORT_H__
  11
  12 //
  13 // The structure representing a range of block numbers, [Start, End].
  14 // It is used to remember the holes in the MTFTP block space. If all
  15 // the holes are filled in, then the download or upload has completed.
  16 //
  17 typedef struct {
  18   LIST_ENTRY    Link;
  19   INTN          Start;
  20   INTN          End;
  21   INTN          Round;
  22   INTN          Bound;
  23 } MTFTP4_BLOCK_RANGE;
  24
  25 /**
  26   Initialize the block range for either RRQ or WRQ.
  27
  28   RRQ and WRQ have different requirements for Start and End.
  29   For example, during start up, WRQ initializes its whole valid block range
  30   to [0, 0xffff]. This is because the server will send us a ACK0 to inform us
  31   to start the upload. When the client received ACK0, it will remove 0 from the
  32   range, 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 in
  34   response to the client's RRQ. When received BLOCK1, the client will remove
  35   it from the block range and send an ACK. It also works if there is option
  36   negotiation.
  37
  38   @param  Head                  The block range head to initialize
  39   @param  Start                 The Start block number.
  40   @param  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 Mtftp4InitBlockRange (
  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  Head                  The block range head
  57
  58   @return The first valid block number, -1 if the block range is empty.
  59
  60 **/
  61 INTN
  62 Mtftp4GetNextBlockNum (
  63   IN LIST_ENTRY  *Head
  64   );
  65
  66 /**
  67   Set the last block number of the block range list.
  68
  69   It will remove all the blocks after the Last. MTFTP initialize the block range
  70   to the maximum possible range, such as [0, 0xffff] for WRQ. When it gets the
  71   last block number, it will call this function to set the last block number.
  72
  73   @param  Head                  The block range list
  74   @param  Last                  The last block number
  75
  76 **/
  77 VOID
  78 Mtftp4SetLastBlockNum (
  79   IN LIST_ENTRY  *Head,
  80   IN UINT16      Last
  81   );
  82
  83 /**
  84   Remove the block number from the block range list.
  85
  86   @param  Head                  The block range list to remove from
  87   @param  Num                   The block number to remove
  88   @param  Completed             Whether Num is the last block number.
  89   @param  BlockCounter          The continuous block counter instead of the value after roll-over.
  90
  91   @retval EFI_NOT_FOUND         The block number isn't in the block range list
  92   @retval EFI_SUCCESS           The block number has been removed from the list
  93   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource
  94
  95 **/
  96 EFI_STATUS
  97 Mtftp4RemoveBlockNum (
  98   IN LIST_ENTRY  *Head,
  99   IN UINT16      Num,
 100   IN BOOLEAN     Completed,
 101   OUT UINT64     *BlockCounter
 102   );
 103
 104 /**
 105   Set the timeout for the instance. User a longer time for passive instances.
 106
 107   @param  Instance              The Mtftp session to set time out
 108
 109 **/
 110 VOID
 111 Mtftp4SetTimeout (
 112   IN OUT MTFTP4_PROTOCOL  *Instance
 113   );
 114
 115 /**
 116   Send the packet for the instance.
 117
 118   It will first save a reference to the packet for later retransmission.
 119   Then determine the destination port, listen port for requests, and connected
 120   port for others. At last, send the packet out.
 121
 122   @param  Instance              The Mtftp instance
 123   @param  Packet                The packet to send
 124
 125   @retval EFI_SUCCESS           The packet is sent out
 126   @retval Others                Failed to transmit the packet.
 127
 128 **/
 129 EFI_STATUS
 130 Mtftp4SendPacket (
 131   IN OUT MTFTP4_PROTOCOL  *Instance,
 132   IN OUT NET_BUF          *Packet
 133   );
 134
 135 /**
 136   Build then transmit the request packet for the MTFTP session.
 137
 138   @param  Instance              The Mtftp session
 139
 140   @retval EFI_OUT_OF_RESOURCES  Failed to allocate memory for the request
 141   @retval EFI_SUCCESS           The request is built and sent
 142   @retval Others                Failed to transmit the packet.
 143
 144 **/
 145 EFI_STATUS
 146 Mtftp4SendRequest (
 147   IN MTFTP4_PROTOCOL  *Instance
 148   );
 149
 150 /**
 151   Build then send an error message.
 152
 153   @param  Instance              The MTFTP session
 154   @param  ErrCode               The error code
 155   @param  ErrInfo               The error message
 156
 157   @retval EFI_OUT_OF_RESOURCES  Failed to allocate memory for the error packet
 158   @retval EFI_SUCCESS           The error packet is transmitted.
 159   @retval Others                Failed to transmit the packet.
 160
 161 **/
 162 EFI_STATUS
 163 Mtftp4SendError (
 164   IN MTFTP4_PROTOCOL  *Instance,
 165   IN UINT16           ErrCode,
 166   IN UINT8            *ErrInfo
 167   );
 168
 169 /**
 170   The timer ticking function in TPL_NOTIFY level for the Mtftp service instance.
 171
 172   @param  Event                 The ticking event
 173   @param  Context               The Mtftp service instance
 174
 175 **/
 176 VOID
 177 EFIAPI
 178 Mtftp4OnTimerTickNotifyLevel (
 179   IN EFI_EVENT  Event,
 180   IN VOID       *Context
 181   );
 182
 183 /**
 184   The timer ticking function for the Mtftp service instance.
 185
 186   @param  Event                 The ticking event
 187   @param  Context               The Mtftp service instance
 188
 189 **/
 190 VOID
 191 EFIAPI
 192 Mtftp4OnTimerTick (
 193   IN EFI_EVENT  Event,
 194   IN VOID       *Context
 195   );
 196
 197 #endif