c1d831bda300d0f53bba2289871daac9a1e255c9
[people/cooldavid/gpxe.git] / src / arch / i386 / interface / pxe / pxe_tftp.c
1 /** @file
2  *
3  * PXE TFTP API
4  *
5  */
6
7 /*
8  * Copyright (C) 2004 Michael Brown <mbrown@fensystems.co.uk>.
9  *
10  * This program is free software; you can redistribute it and/or
11  * modify it under the terms of the GNU General Public License as
12  * published by the Free Software Foundation; either version 2 of the
13  * License, or any later version.
14  *
15  * This program is distributed in the hope that it will be useful, but
16  * WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18  * General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License
21  * along with this program; if not, write to the Free Software
22  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
23  */
24
25 FILE_LICENCE ( GPL2_OR_LATER );
26
27 #include <stdlib.h>
28 #include <stdio.h>
29 #include <errno.h>
30 #include <byteswap.h>
31 #include <gpxe/uaccess.h>
32 #include <gpxe/in.h>
33 #include <gpxe/tftp.h>
34 #include <gpxe/xfer.h>
35 #include <gpxe/open.h>
36 #include <gpxe/process.h>
37 #include <pxe.h>
38
39 /** A PXE TFTP connection */
40 struct pxe_tftp_connection {
41         /** Data transfer interface */
42         struct xfer_interface xfer;
43         /** Data buffer */
44         userptr_t buffer;
45         /** Size of data buffer */
46         size_t size;
47         /** Starting offset of data buffer */
48         size_t start;
49         /** File position */
50         size_t offset;
51         /** Maximum file position */
52         size_t max_offset;
53         /** Block size */
54         size_t blksize;
55         /** Block index */
56         unsigned int blkidx;
57         /** Overall return status code */
58         int rc;
59 };
60
61 /** The PXE TFTP connection */
62 static struct pxe_tftp_connection pxe_tftp = {
63         .xfer = XFER_INIT ( &null_xfer_ops ),
64 };
65
66 /**
67  * Close PXE TFTP connection
68  *
69  * @v rc                Final status code
70  */
71 static void pxe_tftp_close ( int rc ) {
72         xfer_nullify ( &pxe_tftp.xfer );
73         xfer_close ( &pxe_tftp.xfer, rc );
74         pxe_tftp.rc = rc;
75 }
76
77 /**
78  * Receive new data
79  *
80  * @v xfer              Data transfer interface
81  * @v iobuf             I/O buffer
82  * @v meta              Transfer metadata
83  * @ret rc              Return status code
84  */
85 static int pxe_tftp_xfer_deliver_iob ( struct xfer_interface *xfer __unused,
86                                        struct io_buffer *iobuf,
87                                        struct xfer_metadata *meta ) {
88         size_t len = iob_len ( iobuf );
89         int rc = 0;
90
91         /* Calculate new buffer position */
92         if ( meta->whence != SEEK_CUR )
93                 pxe_tftp.offset = 0;
94         pxe_tftp.offset += meta->offset;
95
96         /* Copy data block to buffer */
97         if ( len == 0 ) {
98                 /* No data (pure seek); treat as success */
99         } else if ( pxe_tftp.offset < pxe_tftp.start ) {
100                 DBG ( " buffer underrun at %zx (min %zx)",
101                       pxe_tftp.offset, pxe_tftp.start );
102                 rc = -ENOBUFS;
103         } else if ( ( pxe_tftp.offset + len ) >
104                     ( pxe_tftp.start + pxe_tftp.size ) ) {
105                 DBG ( " buffer overrun at %zx (max %zx)",
106                       ( pxe_tftp.offset + len ),
107                       ( pxe_tftp.start + pxe_tftp.size ) );
108                 rc = -ENOBUFS;
109         } else {
110                 copy_to_user ( pxe_tftp.buffer,
111                                ( pxe_tftp.offset - pxe_tftp.start ),
112                                iobuf->data, len );
113         }
114
115         /* Calculate new buffer position */
116         pxe_tftp.offset += len;
117
118         /* Record maximum offset as the file size */
119         if ( pxe_tftp.max_offset < pxe_tftp.offset )
120                 pxe_tftp.max_offset = pxe_tftp.offset;
121
122         /* Terminate transfer on error */
123         if ( rc != 0 )
124                 pxe_tftp_close ( rc );
125
126         free_iob ( iobuf );
127         return rc;
128 }
129
130 /**
131  * Handle close() event
132  *
133  * @v xfer              Data transfer interface
134  * @v rc                Reason for close
135  */
136 static void pxe_tftp_xfer_close ( struct xfer_interface *xfer __unused,
137                                   int rc ) {
138         pxe_tftp_close ( rc );
139 }
140
141 static struct xfer_interface_operations pxe_tftp_xfer_ops = {
142         .close          = pxe_tftp_xfer_close,
143         .vredirect      = xfer_vreopen,
144         .window         = unlimited_xfer_window,
145         .alloc_iob      = default_xfer_alloc_iob,
146         .deliver_iob    = pxe_tftp_xfer_deliver_iob,
147         .deliver_raw    = xfer_deliver_as_iob,
148 };
149
150 /**
151  * Maximum length of a PXE TFTP URI
152  *
153  * The PXE TFTP API provides 128 characters for the filename; the
154  * extra 128 bytes allow for the remainder of the URI.
155  */
156 #define PXE_TFTP_URI_LEN 256
157
158 /**
159  * Open PXE TFTP connection
160  *
161  * @v ipaddress         IP address
162  * @v port              TFTP server port
163  * @v filename          File name
164  * @v blksize           Requested block size
165  * @ret rc              Return status code
166  */
167 static int pxe_tftp_open ( uint32_t ipaddress, unsigned int port,
168                            const unsigned char *filename, size_t blksize ) {
169         char uri_string[PXE_TFTP_URI_LEN];
170         struct in_addr address;
171         int rc;
172
173         /* Intel bug-for-bug hack */
174         pxe_set_cached_filename ( filename );
175
176         /* Reset PXE TFTP connection structure */
177         memset ( &pxe_tftp, 0, sizeof ( pxe_tftp ) );
178         xfer_init ( &pxe_tftp.xfer, &pxe_tftp_xfer_ops, NULL );
179         pxe_tftp.rc = -EINPROGRESS;
180
181         /* Construct URI string */
182         address.s_addr = ipaddress;
183         if ( ! port )
184                 port = htons ( TFTP_PORT );
185         if ( blksize < TFTP_DEFAULT_BLKSIZE )
186                 blksize = TFTP_DEFAULT_BLKSIZE;
187         snprintf ( uri_string, sizeof ( uri_string ),
188                    "tftp://%s:%d%s%s?blksize=%zd",
189                    inet_ntoa ( address ), ntohs ( port ),
190                    ( ( filename[0] == '/' ) ? "" : "/" ), filename, blksize );
191         DBG ( " %s", uri_string );
192
193         /* Open PXE TFTP connection */
194         if ( ( rc = xfer_open_uri_string ( &pxe_tftp.xfer,
195                                            uri_string ) ) != 0 ) {
196                 DBG ( " could not open (%s)\n", strerror ( rc ) );
197                 return rc;
198         }
199
200         return 0;
201 }
202
203 /**
204  * TFTP OPEN
205  *
206  * @v tftp_open                         Pointer to a struct s_PXENV_TFTP_OPEN
207  * @v s_PXENV_TFTP_OPEN::ServerIPAddress TFTP server IP address
208  * @v s_PXENV_TFTP_OPEN::GatewayIPAddress Relay agent IP address, or 0.0.0.0
209  * @v s_PXENV_TFTP_OPEN::FileName       Name of file to open
210  * @v s_PXENV_TFTP_OPEN::TFTPPort       TFTP server UDP port
211  * @v s_PXENV_TFTP_OPEN::PacketSize     TFTP blksize option to request
212  * @ret #PXENV_EXIT_SUCCESS             File was opened
213  * @ret #PXENV_EXIT_FAILURE             File was not opened
214  * @ret s_PXENV_TFTP_OPEN::Status       PXE status code
215  * @ret s_PXENV_TFTP_OPEN::PacketSize   Negotiated blksize
216  * @err #PXENV_STATUS_TFTP_INVALID_PACKET_SIZE Requested blksize too small
217  *
218  * Opens a TFTP connection for downloading a file a block at a time
219  * using pxenv_tftp_read().
220  *
221  * If s_PXENV_TFTP_OPEN::GatewayIPAddress is 0.0.0.0, normal IP
222  * routing will take place.  See the relevant
223  * @ref pxe_routing "implementation note" for more details.
224  *
225  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
226  * value before calling this function in protected mode.  You cannot
227  * call this function with a 32-bit stack segment.  (See the relevant
228  * @ref pxe_x86_pmode16 "implementation note" for more details.)
229  * 
230  * @note According to the PXE specification version 2.1, this call
231  * "opens a file for reading/writing", though how writing is to be
232  * achieved without the existence of an API call %pxenv_tftp_write()
233  * is not made clear.
234  *
235  * @note Despite the existence of the numerous statements within the
236  * PXE specification of the form "...if a TFTP/MTFTP or UDP connection
237  * is active...", you cannot use pxenv_tftp_open() and
238  * pxenv_tftp_read() to read a file via MTFTP; only via plain old
239  * TFTP.  If you want to use MTFTP, use pxenv_tftp_read_file()
240  * instead.  Astute readers will note that, since
241  * pxenv_tftp_read_file() is an atomic operation from the point of
242  * view of the PXE API, it is conceptually impossible to issue any
243  * other PXE API call "if an MTFTP connection is active".
244  */
245 PXENV_EXIT_t pxenv_tftp_open ( struct s_PXENV_TFTP_OPEN *tftp_open ) {
246         int rc;
247
248         DBG ( "PXENV_TFTP_OPEN" );
249
250         /* Guard against callers that fail to close before re-opening */
251         pxe_tftp_close ( 0 );
252
253         /* Open connection */
254         if ( ( rc = pxe_tftp_open ( tftp_open->ServerIPAddress,
255                                     tftp_open->TFTPPort,
256                                     tftp_open->FileName,
257                                     tftp_open->PacketSize ) ) != 0 ) {
258                 tftp_open->Status = PXENV_STATUS ( rc );
259                 return PXENV_EXIT_FAILURE;
260         }
261
262         /* Wait for OACK to arrive so that we have the block size */
263         while ( ( ( rc = pxe_tftp.rc ) == -EINPROGRESS ) &&
264                 ( pxe_tftp.max_offset == 0 ) ) {
265                 step();
266         }
267         pxe_tftp.blksize = xfer_window ( &pxe_tftp.xfer );
268         tftp_open->PacketSize = pxe_tftp.blksize;
269         DBG ( " blksize=%d", tftp_open->PacketSize );
270
271         /* EINPROGRESS is normal; we don't wait for the whole transfer */
272         if ( rc == -EINPROGRESS )
273                 rc = 0;
274
275         tftp_open->Status = PXENV_STATUS ( rc );
276         return ( rc ? PXENV_EXIT_FAILURE : PXENV_EXIT_SUCCESS );
277 }
278
279 /**
280  * TFTP CLOSE
281  *
282  * @v tftp_close                        Pointer to a struct s_PXENV_TFTP_CLOSE
283  * @ret #PXENV_EXIT_SUCCESS             File was closed successfully
284  * @ret #PXENV_EXIT_FAILURE             File was not closed
285  * @ret s_PXENV_TFTP_CLOSE::Status      PXE status code
286  * @err None                            -
287  *
288  * Close a connection previously opened with pxenv_tftp_open().  You
289  * must have previously opened a connection with pxenv_tftp_open().
290  *
291  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
292  * value before calling this function in protected mode.  You cannot
293  * call this function with a 32-bit stack segment.  (See the relevant
294  * @ref pxe_x86_pmode16 "implementation note" for more details.)
295  */
296 PXENV_EXIT_t pxenv_tftp_close ( struct s_PXENV_TFTP_CLOSE *tftp_close ) {
297         DBG ( "PXENV_TFTP_CLOSE" );
298
299         pxe_tftp_close ( 0 );
300         tftp_close->Status = PXENV_STATUS_SUCCESS;
301         return PXENV_EXIT_SUCCESS;
302 }
303
304 /**
305  * TFTP READ
306  *
307  * @v tftp_read                         Pointer to a struct s_PXENV_TFTP_READ
308  * @v s_PXENV_TFTP_READ::Buffer         Address of data buffer
309  * @ret #PXENV_EXIT_SUCCESS             Data was read successfully
310  * @ret #PXENV_EXIT_FAILURE             Data was not read
311  * @ret s_PXENV_TFTP_READ::Status       PXE status code
312  * @ret s_PXENV_TFTP_READ::PacketNumber TFTP packet number
313  * @ret s_PXENV_TFTP_READ::BufferSize   Length of data written into buffer
314  *
315  * Reads a single packet from a connection previously opened with
316  * pxenv_tftp_open() into the data buffer pointed to by
317  * s_PXENV_TFTP_READ::Buffer.  You must have previously opened a
318  * connection with pxenv_tftp_open().  The data written into
319  * s_PXENV_TFTP_READ::Buffer is just the file data; the various
320  * network headers have already been removed.
321  *
322  * The buffer must be large enough to contain a packet of the size
323  * negotiated via the s_PXENV_TFTP_OPEN::PacketSize field in the
324  * pxenv_tftp_open() call.  It is worth noting that the PXE
325  * specification does @b not require the caller to fill in
326  * s_PXENV_TFTP_READ::BufferSize before calling pxenv_tftp_read(), so
327  * the PXE stack is free to ignore whatever value the caller might
328  * place there and just assume that the buffer is large enough.  That
329  * said, it may be worth the caller always filling in
330  * s_PXENV_TFTP_READ::BufferSize to guard against PXE stacks that
331  * mistake it for an input parameter.
332  *
333  * The length of the TFTP data packet will be returned via
334  * s_PXENV_TFTP_READ::BufferSize.  If this length is less than the
335  * blksize negotiated via s_PXENV_TFTP_OPEN::PacketSize in the call to
336  * pxenv_tftp_open(), this indicates that the block is the last block
337  * in the file.  Note that zero is a valid length for
338  * s_PXENV_TFTP_READ::BufferSize, and will occur when the length of
339  * the file is a multiple of the blksize.
340  *
341  * The PXE specification doesn't actually state that calls to
342  * pxenv_tftp_read() will return the data packets in strict sequential
343  * order, though most PXE stacks will probably do so.  The sequence
344  * number of the packet will be returned in
345  * s_PXENV_TFTP_READ::PacketNumber.  The first packet in the file has
346  * a sequence number of one, not zero.
347  *
348  * To guard against flawed PXE stacks, the caller should probably set
349  * s_PXENV_TFTP_READ::PacketNumber to one less than the expected
350  * returned value (i.e. set it to zero for the first call to
351  * pxenv_tftp_read() and then re-use the returned s_PXENV_TFTP_READ
352  * parameter block for subsequent calls without modifying
353  * s_PXENV_TFTP_READ::PacketNumber between calls).  The caller should
354  * also guard against potential problems caused by flawed
355  * implementations returning the occasional duplicate packet, by
356  * checking that the value returned in s_PXENV_TFTP_READ::PacketNumber
357  * is as expected (i.e. one greater than that returned from the
358  * previous call to pxenv_tftp_read()).
359  *
360  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
361  * value before calling this function in protected mode.  You cannot
362  * call this function with a 32-bit stack segment.  (See the relevant
363  * @ref pxe_x86_pmode16 "implementation note" for more details.)
364  */
365 PXENV_EXIT_t pxenv_tftp_read ( struct s_PXENV_TFTP_READ *tftp_read ) {
366         int rc;
367
368         DBG ( "PXENV_TFTP_READ to %04x:%04x",
369               tftp_read->Buffer.segment, tftp_read->Buffer.offset );
370
371         /* Read single block into buffer */
372         pxe_tftp.buffer = real_to_user ( tftp_read->Buffer.segment,
373                                          tftp_read->Buffer.offset );
374         pxe_tftp.size = pxe_tftp.blksize;
375         pxe_tftp.start = pxe_tftp.offset;
376         while ( ( ( rc = pxe_tftp.rc ) == -EINPROGRESS ) &&
377                 ( pxe_tftp.offset == pxe_tftp.start ) )
378                 step();
379         pxe_tftp.buffer = UNULL;
380         tftp_read->BufferSize = ( pxe_tftp.offset - pxe_tftp.start );
381         tftp_read->PacketNumber = ++pxe_tftp.blkidx;
382
383         /* EINPROGRESS is normal if we haven't reached EOF yet */
384         if ( rc == -EINPROGRESS )
385                 rc = 0;
386
387         tftp_read->Status = PXENV_STATUS ( rc );
388         return ( rc ? PXENV_EXIT_FAILURE : PXENV_EXIT_SUCCESS );
389 }
390
391 /**
392  * TFTP/MTFTP read file
393  *
394  * @v tftp_read_file                 Pointer to a struct s_PXENV_TFTP_READ_FILE
395  * @v s_PXENV_TFTP_READ_FILE::FileName          File name
396  * @v s_PXENV_TFTP_READ_FILE::BufferSize        Size of the receive buffer
397  * @v s_PXENV_TFTP_READ_FILE::Buffer            Address of the receive buffer
398  * @v s_PXENV_TFTP_READ_FILE::ServerIPAddress   TFTP server IP address
399  * @v s_PXENV_TFTP_READ_FILE::GatewayIPAddress  Relay agent IP address
400  * @v s_PXENV_TFTP_READ_FILE::McastIPAddress    File's multicast IP address
401  * @v s_PXENV_TFTP_READ_FILE::TFTPClntPort      Client multicast UDP port
402  * @v s_PXENV_TFTP_READ_FILE::TFTPSrvPort       Server multicast UDP port
403  * @v s_PXENV_TFTP_READ_FILE::TFTPOpenTimeOut   Time to wait for first packet
404  * @v s_PXENV_TFTP_READ_FILE::TFTPReopenDelay   MTFTP inactivity timeout
405  * @ret #PXENV_EXIT_SUCCESS                     File downloaded successfully
406  * @ret #PXENV_EXIT_FAILURE                     File not downloaded
407  * @ret s_PXENV_TFTP_READ_FILE::Status          PXE status code
408  * @ret s_PXENV_TFTP_READ_FILE::BufferSize      Length of downloaded file
409  *
410  * Downloads an entire file via either TFTP or MTFTP into the buffer
411  * pointed to by s_PXENV_TFTP_READ_FILE::Buffer.
412  *
413  * The PXE specification does not make it clear how the caller
414  * requests that MTFTP be used rather than TFTP (or vice versa).  One
415  * reasonable guess is that setting
416  * s_PXENV_TFTP_READ_FILE::McastIPAddress to 0.0.0.0 would cause TFTP
417  * to be used instead of MTFTP, though it is conceivable that some PXE
418  * stacks would interpret that as "use the DHCP-provided multicast IP
419  * address" instead.  Some PXE stacks will not implement MTFTP at all,
420  * and will always use TFTP.
421  *
422  * It is not specified whether or not
423  * s_PXENV_TFTP_READ_FILE::TFTPSrvPort will be used as the TFTP server
424  * port for TFTP (rather than MTFTP) downloads.  Callers should assume
425  * that the only way to access a TFTP server on a non-standard port is
426  * to use pxenv_tftp_open() and pxenv_tftp_read().
427  *
428  * If s_PXENV_TFTP_READ_FILE::GatewayIPAddress is 0.0.0.0, normal IP
429  * routing will take place.  See the relevant
430  * @ref pxe_routing "implementation note" for more details.
431  *
432  * It is interesting to note that s_PXENV_TFTP_READ_FILE::Buffer is an
433  * #ADDR32_t type, i.e. nominally a flat physical address.  Some PXE
434  * NBPs (e.g. NTLDR) are known to call pxenv_tftp_read_file() in real
435  * mode with s_PXENV_TFTP_READ_FILE::Buffer set to an address above
436  * 1MB.  This means that PXE stacks must be prepared to write to areas
437  * outside base memory.  Exactly how this is to be achieved is not
438  * specified, though using INT 15,87 is as close to a standard method
439  * as any, and should probably be used.  Switching to protected-mode
440  * in order to access high memory will fail if pxenv_tftp_read_file()
441  * is called in V86 mode; it is reasonably to expect that a V86
442  * monitor would intercept the relatively well-defined INT 15,87 if it
443  * wants the PXE stack to be able to write to high memory.
444  *
445  * Things get even more interesting if pxenv_tftp_read_file() is
446  * called in protected mode, because there is then absolutely no way
447  * for the PXE stack to write to an absolute physical address.  You
448  * can't even get around the problem by creating a special "access
449  * everything" segment in the s_PXE data structure, because the
450  * #SEGDESC_t descriptors are limited to 64kB in size.
451  *
452  * Previous versions of the PXE specification (e.g. WfM 1.1a) provide
453  * a separate API call, %pxenv_tftp_read_file_pmode(), specifically to
454  * work around this problem.  The s_PXENV_TFTP_READ_FILE_PMODE
455  * parameter block splits s_PXENV_TFTP_READ_FILE::Buffer into
456  * s_PXENV_TFTP_READ_FILE_PMODE::BufferSelector and
457  * s_PXENV_TFTP_READ_FILE_PMODE::BufferOffset, i.e. it provides a
458  * protected-mode segment:offset address for the data buffer.  This
459  * API call is no longer present in version 2.1 of the PXE
460  * specification.
461  *
462  * Etherboot makes the assumption that s_PXENV_TFTP_READ_FILE::Buffer
463  * is an offset relative to the caller's data segment, when
464  * pxenv_tftp_read_file() is called in protected mode.
465  *
466  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
467  * value before calling this function in protected mode.  You cannot
468  * call this function with a 32-bit stack segment.  (See the relevant
469  * @ref pxe_x86_pmode16 "implementation note" for more details.)
470  *
471  * @note Microsoft's NTLDR assumes that the filename passed in via
472  * s_PXENV_TFTP_READ_FILE::FileName will be stored in the "file" field
473  * of the stored DHCPACK packet, whence it will be returned via any
474  * subsequent calls to pxenv_get_cached_info().  Though this is
475  * essentially a bug in the Intel PXE implementation (not, for once,
476  * in the specification!), it is a bug that Microsoft relies upon, and
477  * so we implement this bug-for-bug compatibility by overwriting the
478  * filename stored DHCPACK packet with the filename passed in
479  * s_PXENV_TFTP_READ_FILE::FileName.
480  *
481  */
482 PXENV_EXIT_t pxenv_tftp_read_file ( struct s_PXENV_TFTP_READ_FILE
483                                     *tftp_read_file ) {
484         int rc;
485
486         DBG ( "PXENV_TFTP_READ_FILE to %08x+%x", tftp_read_file->Buffer,
487               tftp_read_file->BufferSize );
488
489         /* Open TFTP file */
490         if ( ( rc = pxe_tftp_open ( tftp_read_file->ServerIPAddress, 0,
491                                     tftp_read_file->FileName, 0 ) ) != 0 ) {
492                 tftp_read_file->Status = PXENV_STATUS ( rc );
493                 return PXENV_EXIT_FAILURE;
494         }
495
496         /* Read entire file */
497         pxe_tftp.buffer = phys_to_user ( tftp_read_file->Buffer );
498         pxe_tftp.size = tftp_read_file->BufferSize;
499         while ( ( rc = pxe_tftp.rc ) == -EINPROGRESS )
500                 step();
501         pxe_tftp.buffer = UNULL;
502         tftp_read_file->BufferSize = pxe_tftp.max_offset;
503
504         /* Close TFTP file */
505         pxe_tftp_close ( rc );
506
507         tftp_read_file->Status = PXENV_STATUS ( rc );
508         return ( rc ? PXENV_EXIT_FAILURE : PXENV_EXIT_SUCCESS );
509 }
510
511 /**
512  * TFTP GET FILE SIZE
513  *
514  * @v tftp_get_fsize                 Pointer to a struct s_PXENV_TFTP_GET_FSIZE
515  * @v s_PXENV_TFTP_GET_FSIZE::ServerIPAddress   TFTP server IP address
516  * @v s_PXENV_TFTP_GET_FSIZE::GatewayIPAddress  Relay agent IP address
517  * @v s_PXENV_TFTP_GET_FSIZE::FileName  File name
518  * @ret #PXENV_EXIT_SUCCESS             File size was determined successfully
519  * @ret #PXENV_EXIT_FAILURE             File size was not determined
520  * @ret s_PXENV_TFTP_GET_FSIZE::Status  PXE status code
521  * @ret s_PXENV_TFTP_GET_FSIZE::FileSize        File size
522  *
523  * Determine the size of a file on a TFTP server.  This uses the
524  * "tsize" TFTP option, and so will not work with a TFTP server that
525  * does not support TFTP options, or that does not support the "tsize"
526  * option.
527  *
528  * The PXE specification states that this API call will @b not open a
529  * TFTP connection for subsequent use with pxenv_tftp_read().  (This
530  * is somewhat daft, since the only way to obtain the file size via
531  * the "tsize" option involves issuing a TFTP open request, but that's
532  * life.)
533  *
534  * You cannot call pxenv_tftp_get_fsize() while a TFTP or UDP
535  * connection is open.
536  *
537  * If s_PXENV_TFTP_GET_FSIZE::GatewayIPAddress is 0.0.0.0, normal IP
538  * routing will take place.  See the relevant
539  * @ref pxe_routing "implementation note" for more details.
540  *
541  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
542  * value before calling this function in protected mode.  You cannot
543  * call this function with a 32-bit stack segment.  (See the relevant
544  * @ref pxe_x86_pmode16 "implementation note" for more details.)
545  * 
546  * @note There is no way to specify the TFTP server port with this API
547  * call.  Though you can open a file using a non-standard TFTP server
548  * port (via s_PXENV_TFTP_OPEN::TFTPPort or, potentially,
549  * s_PXENV_TFTP_READ_FILE::TFTPSrvPort), you can only get the size of
550  * a file from a TFTP server listening on the standard TFTP port.
551  * "Consistency" is not a word in Intel's vocabulary.
552  */
553 PXENV_EXIT_t pxenv_tftp_get_fsize ( struct s_PXENV_TFTP_GET_FSIZE
554                                     *tftp_get_fsize ) {
555         int rc;
556
557         DBG ( "PXENV_TFTP_GET_FSIZE" );
558
559         /* Open TFTP file */
560         if ( ( rc = pxe_tftp_open ( tftp_get_fsize->ServerIPAddress, 0,
561                                     tftp_get_fsize->FileName, 0 ) ) != 0 ) {
562                 tftp_get_fsize->Status = PXENV_STATUS ( rc );
563                 return PXENV_EXIT_FAILURE;
564         }
565
566         /* Wait for initial seek to arrive, and record size */
567         while ( ( ( rc = pxe_tftp.rc ) == -EINPROGRESS ) &&
568                 ( pxe_tftp.max_offset == 0 ) ) {
569                 step();
570         }
571         tftp_get_fsize->FileSize = pxe_tftp.max_offset;
572         DBG ( " fsize=%d", tftp_get_fsize->FileSize );
573
574         /* EINPROGRESS is normal; we don't wait for the whole transfer */
575         if ( rc == -EINPROGRESS )
576                 rc = 0;
577
578         /* Close TFTP file */
579         pxe_tftp_close ( rc );
580
581         tftp_get_fsize->Status = PXENV_STATUS ( rc );
582         return ( rc ? PXENV_EXIT_FAILURE : PXENV_EXIT_SUCCESS );
583 }