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