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