MdeModulePkg/Universal/Network/Mtftp4Dxe/Mtftp4Support.h

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