• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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  */
pxe_tftp_close(int rc)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  */
pxe_tftp_xfer_deliver_iob(struct xfer_interface * xfer __unused,struct io_buffer * iobuf,struct xfer_metadata * meta)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  */
pxe_tftp_xfer_close(struct xfer_interface * xfer __unused,int rc)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  */
pxe_tftp_open(uint32_t ipaddress,unsigned int port,const unsigned char * filename,size_t blksize,int sizeonly)167 static int pxe_tftp_open ( uint32_t ipaddress, unsigned int port,
168 			   const unsigned char *filename, size_t blksize,
169 			   int sizeonly ) {
170 	char uri_string[PXE_TFTP_URI_LEN];
171 	struct in_addr address;
172 	int rc;
173 
174 	/* Intel bug-for-bug hack */
175 	pxe_set_cached_filename ( filename );
176 
177 	/* Reset PXE TFTP connection structure */
178 	memset ( &pxe_tftp, 0, sizeof ( pxe_tftp ) );
179 	xfer_init ( &pxe_tftp.xfer, &pxe_tftp_xfer_ops, NULL );
180 	pxe_tftp.rc = -EINPROGRESS;
181 
182 	/* Construct URI string */
183 	address.s_addr = ipaddress;
184 	if ( ! port )
185 		port = htons ( TFTP_PORT );
186 	if ( blksize < TFTP_DEFAULT_BLKSIZE )
187 		blksize = TFTP_DEFAULT_BLKSIZE;
188 	snprintf ( uri_string, sizeof ( uri_string ),
189 		   "tftp%s://%s:%d%s%s?blksize=%zd",
190 		   sizeonly ? "size" : "",
191 		   inet_ntoa ( address ), ntohs ( port ),
192 		   ( ( filename[0] == '/' ) ? "" : "/" ), filename, blksize );
193 	DBG ( " %s", uri_string );
194 
195 	/* Open PXE TFTP connection */
196 	if ( ( rc = xfer_open_uri_string ( &pxe_tftp.xfer,
197 					   uri_string ) ) != 0 ) {
198 		DBG ( " could not open (%s)\n", strerror ( rc ) );
199 		return rc;
200 	}
201 
202 	return 0;
203 }
204 
205 /**
206  * TFTP OPEN
207  *
208  * @v tftp_open				Pointer to a struct s_PXENV_TFTP_OPEN
209  * @v s_PXENV_TFTP_OPEN::ServerIPAddress TFTP server IP address
210  * @v s_PXENV_TFTP_OPEN::GatewayIPAddress Relay agent IP address, or 0.0.0.0
211  * @v s_PXENV_TFTP_OPEN::FileName	Name of file to open
212  * @v s_PXENV_TFTP_OPEN::TFTPPort	TFTP server UDP port
213  * @v s_PXENV_TFTP_OPEN::PacketSize	TFTP blksize option to request
214  * @ret #PXENV_EXIT_SUCCESS		File was opened
215  * @ret #PXENV_EXIT_FAILURE		File was not opened
216  * @ret s_PXENV_TFTP_OPEN::Status	PXE status code
217  * @ret s_PXENV_TFTP_OPEN::PacketSize	Negotiated blksize
218  * @err #PXENV_STATUS_TFTP_INVALID_PACKET_SIZE Requested blksize too small
219  *
220  * Opens a TFTP connection for downloading a file a block at a time
221  * using pxenv_tftp_read().
222  *
223  * If s_PXENV_TFTP_OPEN::GatewayIPAddress is 0.0.0.0, normal IP
224  * routing will take place.  See the relevant
225  * @ref pxe_routing "implementation note" for more details.
226  *
227  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
228  * value before calling this function in protected mode.  You cannot
229  * call this function with a 32-bit stack segment.  (See the relevant
230  * @ref pxe_x86_pmode16 "implementation note" for more details.)
231  *
232  * @note According to the PXE specification version 2.1, this call
233  * "opens a file for reading/writing", though how writing is to be
234  * achieved without the existence of an API call %pxenv_tftp_write()
235  * is not made clear.
236  *
237  * @note Despite the existence of the numerous statements within the
238  * PXE specification of the form "...if a TFTP/MTFTP or UDP connection
239  * is active...", you cannot use pxenv_tftp_open() and
240  * pxenv_tftp_read() to read a file via MTFTP; only via plain old
241  * TFTP.  If you want to use MTFTP, use pxenv_tftp_read_file()
242  * instead.  Astute readers will note that, since
243  * pxenv_tftp_read_file() is an atomic operation from the point of
244  * view of the PXE API, it is conceptually impossible to issue any
245  * other PXE API call "if an MTFTP connection is active".
246  */
pxenv_tftp_open(struct s_PXENV_TFTP_OPEN * tftp_open)247 PXENV_EXIT_t pxenv_tftp_open ( struct s_PXENV_TFTP_OPEN *tftp_open ) {
248 	int rc;
249 
250 	DBG ( "PXENV_TFTP_OPEN" );
251 
252 	/* Guard against callers that fail to close before re-opening */
253 	pxe_tftp_close ( 0 );
254 
255 	/* Open connection */
256 	if ( ( rc = pxe_tftp_open ( tftp_open->ServerIPAddress,
257 				    tftp_open->TFTPPort,
258 				    tftp_open->FileName,
259 				    tftp_open->PacketSize,
260 				    0) ) != 0 ) {
261 		tftp_open->Status = PXENV_STATUS ( rc );
262 		return PXENV_EXIT_FAILURE;
263 	}
264 
265 	/* Wait for OACK to arrive so that we have the block size */
266 	while ( ( ( rc = pxe_tftp.rc ) == -EINPROGRESS ) &&
267 		( pxe_tftp.max_offset == 0 ) ) {
268 		step();
269 	}
270 	pxe_tftp.blksize = xfer_window ( &pxe_tftp.xfer );
271 	tftp_open->PacketSize = pxe_tftp.blksize;
272 	DBG ( " blksize=%d", tftp_open->PacketSize );
273 
274 	/* EINPROGRESS is normal; we don't wait for the whole transfer */
275 	if ( rc == -EINPROGRESS )
276 		rc = 0;
277 
278 	tftp_open->Status = PXENV_STATUS ( rc );
279 	return ( rc ? PXENV_EXIT_FAILURE : PXENV_EXIT_SUCCESS );
280 }
281 
282 /**
283  * TFTP CLOSE
284  *
285  * @v tftp_close			Pointer to a struct s_PXENV_TFTP_CLOSE
286  * @ret #PXENV_EXIT_SUCCESS		File was closed successfully
287  * @ret #PXENV_EXIT_FAILURE		File was not closed
288  * @ret s_PXENV_TFTP_CLOSE::Status	PXE status code
289  * @err None				-
290  *
291  * Close a connection previously opened with pxenv_tftp_open().  You
292  * must have previously opened a connection with pxenv_tftp_open().
293  *
294  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
295  * value before calling this function in protected mode.  You cannot
296  * call this function with a 32-bit stack segment.  (See the relevant
297  * @ref pxe_x86_pmode16 "implementation note" for more details.)
298  */
pxenv_tftp_close(struct s_PXENV_TFTP_CLOSE * tftp_close)299 PXENV_EXIT_t pxenv_tftp_close ( struct s_PXENV_TFTP_CLOSE *tftp_close ) {
300 	DBG ( "PXENV_TFTP_CLOSE" );
301 
302 	pxe_tftp_close ( 0 );
303 	tftp_close->Status = PXENV_STATUS_SUCCESS;
304 	return PXENV_EXIT_SUCCESS;
305 }
306 
307 /**
308  * TFTP READ
309  *
310  * @v tftp_read				Pointer to a struct s_PXENV_TFTP_READ
311  * @v s_PXENV_TFTP_READ::Buffer		Address of data buffer
312  * @ret #PXENV_EXIT_SUCCESS		Data was read successfully
313  * @ret #PXENV_EXIT_FAILURE		Data was not read
314  * @ret s_PXENV_TFTP_READ::Status	PXE status code
315  * @ret s_PXENV_TFTP_READ::PacketNumber	TFTP packet number
316  * @ret s_PXENV_TFTP_READ::BufferSize	Length of data written into buffer
317  *
318  * Reads a single packet from a connection previously opened with
319  * pxenv_tftp_open() into the data buffer pointed to by
320  * s_PXENV_TFTP_READ::Buffer.  You must have previously opened a
321  * connection with pxenv_tftp_open().  The data written into
322  * s_PXENV_TFTP_READ::Buffer is just the file data; the various
323  * network headers have already been removed.
324  *
325  * The buffer must be large enough to contain a packet of the size
326  * negotiated via the s_PXENV_TFTP_OPEN::PacketSize field in the
327  * pxenv_tftp_open() call.  It is worth noting that the PXE
328  * specification does @b not require the caller to fill in
329  * s_PXENV_TFTP_READ::BufferSize before calling pxenv_tftp_read(), so
330  * the PXE stack is free to ignore whatever value the caller might
331  * place there and just assume that the buffer is large enough.  That
332  * said, it may be worth the caller always filling in
333  * s_PXENV_TFTP_READ::BufferSize to guard against PXE stacks that
334  * mistake it for an input parameter.
335  *
336  * The length of the TFTP data packet will be returned via
337  * s_PXENV_TFTP_READ::BufferSize.  If this length is less than the
338  * blksize negotiated via s_PXENV_TFTP_OPEN::PacketSize in the call to
339  * pxenv_tftp_open(), this indicates that the block is the last block
340  * in the file.  Note that zero is a valid length for
341  * s_PXENV_TFTP_READ::BufferSize, and will occur when the length of
342  * the file is a multiple of the blksize.
343  *
344  * The PXE specification doesn't actually state that calls to
345  * pxenv_tftp_read() will return the data packets in strict sequential
346  * order, though most PXE stacks will probably do so.  The sequence
347  * number of the packet will be returned in
348  * s_PXENV_TFTP_READ::PacketNumber.  The first packet in the file has
349  * a sequence number of one, not zero.
350  *
351  * To guard against flawed PXE stacks, the caller should probably set
352  * s_PXENV_TFTP_READ::PacketNumber to one less than the expected
353  * returned value (i.e. set it to zero for the first call to
354  * pxenv_tftp_read() and then re-use the returned s_PXENV_TFTP_READ
355  * parameter block for subsequent calls without modifying
356  * s_PXENV_TFTP_READ::PacketNumber between calls).  The caller should
357  * also guard against potential problems caused by flawed
358  * implementations returning the occasional duplicate packet, by
359  * checking that the value returned in s_PXENV_TFTP_READ::PacketNumber
360  * is as expected (i.e. one greater than that returned from the
361  * previous call to pxenv_tftp_read()).
362  *
363  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
364  * value before calling this function in protected mode.  You cannot
365  * call this function with a 32-bit stack segment.  (See the relevant
366  * @ref pxe_x86_pmode16 "implementation note" for more details.)
367  */
pxenv_tftp_read(struct s_PXENV_TFTP_READ * tftp_read)368 PXENV_EXIT_t pxenv_tftp_read ( struct s_PXENV_TFTP_READ *tftp_read ) {
369 	int rc;
370 
371 	DBG ( "PXENV_TFTP_READ to %04x:%04x",
372 	      tftp_read->Buffer.segment, tftp_read->Buffer.offset );
373 
374 	/* Read single block into buffer */
375 	pxe_tftp.buffer = real_to_user ( tftp_read->Buffer.segment,
376 					 tftp_read->Buffer.offset );
377 	pxe_tftp.size = pxe_tftp.blksize;
378 	pxe_tftp.start = pxe_tftp.offset;
379 	while ( ( ( rc = pxe_tftp.rc ) == -EINPROGRESS ) &&
380 		( pxe_tftp.offset == pxe_tftp.start ) )
381 		step();
382 	pxe_tftp.buffer = UNULL;
383 	tftp_read->BufferSize = ( pxe_tftp.offset - pxe_tftp.start );
384 	tftp_read->PacketNumber = ++pxe_tftp.blkidx;
385 
386 	/* EINPROGRESS is normal if we haven't reached EOF yet */
387 	if ( rc == -EINPROGRESS )
388 		rc = 0;
389 
390 	tftp_read->Status = PXENV_STATUS ( rc );
391 	return ( rc ? PXENV_EXIT_FAILURE : PXENV_EXIT_SUCCESS );
392 }
393 
394 /**
395  * TFTP/MTFTP read file
396  *
397  * @v tftp_read_file		     Pointer to a struct s_PXENV_TFTP_READ_FILE
398  * @v s_PXENV_TFTP_READ_FILE::FileName		File name
399  * @v s_PXENV_TFTP_READ_FILE::BufferSize 	Size of the receive buffer
400  * @v s_PXENV_TFTP_READ_FILE::Buffer		Address of the receive buffer
401  * @v s_PXENV_TFTP_READ_FILE::ServerIPAddress	TFTP server IP address
402  * @v s_PXENV_TFTP_READ_FILE::GatewayIPAddress	Relay agent IP address
403  * @v s_PXENV_TFTP_READ_FILE::McastIPAddress	File's multicast IP address
404  * @v s_PXENV_TFTP_READ_FILE::TFTPClntPort	Client multicast UDP port
405  * @v s_PXENV_TFTP_READ_FILE::TFTPSrvPort	Server multicast UDP port
406  * @v s_PXENV_TFTP_READ_FILE::TFTPOpenTimeOut	Time to wait for first packet
407  * @v s_PXENV_TFTP_READ_FILE::TFTPReopenDelay	MTFTP inactivity timeout
408  * @ret #PXENV_EXIT_SUCCESS			File downloaded successfully
409  * @ret #PXENV_EXIT_FAILURE			File not downloaded
410  * @ret s_PXENV_TFTP_READ_FILE::Status		PXE status code
411  * @ret s_PXENV_TFTP_READ_FILE::BufferSize	Length of downloaded file
412  *
413  * Downloads an entire file via either TFTP or MTFTP into the buffer
414  * pointed to by s_PXENV_TFTP_READ_FILE::Buffer.
415  *
416  * The PXE specification does not make it clear how the caller
417  * requests that MTFTP be used rather than TFTP (or vice versa).  One
418  * reasonable guess is that setting
419  * s_PXENV_TFTP_READ_FILE::McastIPAddress to 0.0.0.0 would cause TFTP
420  * to be used instead of MTFTP, though it is conceivable that some PXE
421  * stacks would interpret that as "use the DHCP-provided multicast IP
422  * address" instead.  Some PXE stacks will not implement MTFTP at all,
423  * and will always use TFTP.
424  *
425  * It is not specified whether or not
426  * s_PXENV_TFTP_READ_FILE::TFTPSrvPort will be used as the TFTP server
427  * port for TFTP (rather than MTFTP) downloads.  Callers should assume
428  * that the only way to access a TFTP server on a non-standard port is
429  * to use pxenv_tftp_open() and pxenv_tftp_read().
430  *
431  * If s_PXENV_TFTP_READ_FILE::GatewayIPAddress is 0.0.0.0, normal IP
432  * routing will take place.  See the relevant
433  * @ref pxe_routing "implementation note" for more details.
434  *
435  * It is interesting to note that s_PXENV_TFTP_READ_FILE::Buffer is an
436  * #ADDR32_t type, i.e. nominally a flat physical address.  Some PXE
437  * NBPs (e.g. NTLDR) are known to call pxenv_tftp_read_file() in real
438  * mode with s_PXENV_TFTP_READ_FILE::Buffer set to an address above
439  * 1MB.  This means that PXE stacks must be prepared to write to areas
440  * outside base memory.  Exactly how this is to be achieved is not
441  * specified, though using INT 15,87 is as close to a standard method
442  * as any, and should probably be used.  Switching to protected-mode
443  * in order to access high memory will fail if pxenv_tftp_read_file()
444  * is called in V86 mode; it is reasonably to expect that a V86
445  * monitor would intercept the relatively well-defined INT 15,87 if it
446  * wants the PXE stack to be able to write to high memory.
447  *
448  * Things get even more interesting if pxenv_tftp_read_file() is
449  * called in protected mode, because there is then absolutely no way
450  * for the PXE stack to write to an absolute physical address.  You
451  * can't even get around the problem by creating a special "access
452  * everything" segment in the s_PXE data structure, because the
453  * #SEGDESC_t descriptors are limited to 64kB in size.
454  *
455  * Previous versions of the PXE specification (e.g. WfM 1.1a) provide
456  * a separate API call, %pxenv_tftp_read_file_pmode(), specifically to
457  * work around this problem.  The s_PXENV_TFTP_READ_FILE_PMODE
458  * parameter block splits s_PXENV_TFTP_READ_FILE::Buffer into
459  * s_PXENV_TFTP_READ_FILE_PMODE::BufferSelector and
460  * s_PXENV_TFTP_READ_FILE_PMODE::BufferOffset, i.e. it provides a
461  * protected-mode segment:offset address for the data buffer.  This
462  * API call is no longer present in version 2.1 of the PXE
463  * specification.
464  *
465  * Etherboot makes the assumption that s_PXENV_TFTP_READ_FILE::Buffer
466  * is an offset relative to the caller's data segment, when
467  * pxenv_tftp_read_file() is called in protected mode.
468  *
469  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
470  * value before calling this function in protected mode.  You cannot
471  * call this function with a 32-bit stack segment.  (See the relevant
472  * @ref pxe_x86_pmode16 "implementation note" for more details.)
473  *
474  * @note Microsoft's NTLDR assumes that the filename passed in via
475  * s_PXENV_TFTP_READ_FILE::FileName will be stored in the "file" field
476  * of the stored DHCPACK packet, whence it will be returned via any
477  * subsequent calls to pxenv_get_cached_info().  Though this is
478  * essentially a bug in the Intel PXE implementation (not, for once,
479  * in the specification!), it is a bug that Microsoft relies upon, and
480  * so we implement this bug-for-bug compatibility by overwriting the
481  * filename stored DHCPACK packet with the filename passed in
482  * s_PXENV_TFTP_READ_FILE::FileName.
483  *
484  */
pxenv_tftp_read_file(struct s_PXENV_TFTP_READ_FILE * tftp_read_file)485 PXENV_EXIT_t pxenv_tftp_read_file ( struct s_PXENV_TFTP_READ_FILE
486 				    *tftp_read_file ) {
487 	int rc;
488 
489 	DBG ( "PXENV_TFTP_READ_FILE to %08x+%x", tftp_read_file->Buffer,
490 	      tftp_read_file->BufferSize );
491 
492 	/* Open TFTP file */
493 	if ( ( rc = pxe_tftp_open ( tftp_read_file->ServerIPAddress, 0,
494 				    tftp_read_file->FileName, 0, 0 ) ) != 0 ) {
495 		tftp_read_file->Status = PXENV_STATUS ( rc );
496 		return PXENV_EXIT_FAILURE;
497 	}
498 
499 	/* Read entire file */
500 	pxe_tftp.buffer = phys_to_user ( tftp_read_file->Buffer );
501 	pxe_tftp.size = tftp_read_file->BufferSize;
502 	while ( ( rc = pxe_tftp.rc ) == -EINPROGRESS )
503 		step();
504 	pxe_tftp.buffer = UNULL;
505 	tftp_read_file->BufferSize = pxe_tftp.max_offset;
506 
507 	/* Close TFTP file */
508 	pxe_tftp_close ( rc );
509 
510 	tftp_read_file->Status = PXENV_STATUS ( rc );
511 	return ( rc ? PXENV_EXIT_FAILURE : PXENV_EXIT_SUCCESS );
512 }
513 
514 /**
515  * TFTP GET FILE SIZE
516  *
517  * @v tftp_get_fsize		     Pointer to a struct s_PXENV_TFTP_GET_FSIZE
518  * @v s_PXENV_TFTP_GET_FSIZE::ServerIPAddress	TFTP server IP address
519  * @v s_PXENV_TFTP_GET_FSIZE::GatewayIPAddress	Relay agent IP address
520  * @v s_PXENV_TFTP_GET_FSIZE::FileName	File name
521  * @ret #PXENV_EXIT_SUCCESS		File size was determined successfully
522  * @ret #PXENV_EXIT_FAILURE		File size was not determined
523  * @ret s_PXENV_TFTP_GET_FSIZE::Status	PXE status code
524  * @ret s_PXENV_TFTP_GET_FSIZE::FileSize	File size
525  *
526  * Determine the size of a file on a TFTP server.  This uses the
527  * "tsize" TFTP option, and so will not work with a TFTP server that
528  * does not support TFTP options, or that does not support the "tsize"
529  * option.
530  *
531  * The PXE specification states that this API call will @b not open a
532  * TFTP connection for subsequent use with pxenv_tftp_read().  (This
533  * is somewhat daft, since the only way to obtain the file size via
534  * the "tsize" option involves issuing a TFTP open request, but that's
535  * life.)
536  *
537  * You cannot call pxenv_tftp_get_fsize() while a TFTP or UDP
538  * connection is open.
539  *
540  * If s_PXENV_TFTP_GET_FSIZE::GatewayIPAddress is 0.0.0.0, normal IP
541  * routing will take place.  See the relevant
542  * @ref pxe_routing "implementation note" for more details.
543  *
544  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
545  * value before calling this function in protected mode.  You cannot
546  * call this function with a 32-bit stack segment.  (See the relevant
547  * @ref pxe_x86_pmode16 "implementation note" for more details.)
548  *
549  * @note There is no way to specify the TFTP server port with this API
550  * call.  Though you can open a file using a non-standard TFTP server
551  * port (via s_PXENV_TFTP_OPEN::TFTPPort or, potentially,
552  * s_PXENV_TFTP_READ_FILE::TFTPSrvPort), you can only get the size of
553  * a file from a TFTP server listening on the standard TFTP port.
554  * "Consistency" is not a word in Intel's vocabulary.
555  */
pxenv_tftp_get_fsize(struct s_PXENV_TFTP_GET_FSIZE * tftp_get_fsize)556 PXENV_EXIT_t pxenv_tftp_get_fsize ( struct s_PXENV_TFTP_GET_FSIZE
557 				    *tftp_get_fsize ) {
558 	int rc;
559 
560 	DBG ( "PXENV_TFTP_GET_FSIZE" );
561 
562 	/* Open TFTP file */
563 	if ( ( rc = pxe_tftp_open ( tftp_get_fsize->ServerIPAddress, 0,
564 				    tftp_get_fsize->FileName, 0, 1 ) ) != 0 ) {
565 		tftp_get_fsize->Status = PXENV_STATUS ( rc );
566 		return PXENV_EXIT_FAILURE;
567 	}
568 
569 	/* Wait for initial seek to arrive, and record size */
570 	while ( ( ( rc = pxe_tftp.rc ) == -EINPROGRESS ) &&
571 		( pxe_tftp.max_offset == 0 ) ) {
572 		step();
573 	}
574 	tftp_get_fsize->FileSize = pxe_tftp.max_offset;
575 	DBG ( " fsize=%d", tftp_get_fsize->FileSize );
576 
577 	/* EINPROGRESS is normal; we don't wait for the whole transfer */
578 	if ( rc == -EINPROGRESS )
579 		rc = 0;
580 
581 	/* Close TFTP file */
582 	pxe_tftp_close ( rc );
583 
584 	tftp_get_fsize->Status = PXENV_STATUS ( rc );
585 	return ( rc ? PXENV_EXIT_FAILURE : PXENV_EXIT_SUCCESS );
586 }
587