56529b1555772eb3bcecc6854904f8cdecd0692a
[people/pcmattman/gpxe.git] / src / 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 #include <stdlib.h>
26 #include <stdio.h>
27 #include <byteswap.h>
28 #include <gpxe/uaccess.h>
29 #include <gpxe/in.h>
30 #include <gpxe/tftp.h>
31 #include <gpxe/posix_io.h>
32 #include <pxe.h>
33
34 /** File descriptor for "single-file-only" PXE TFTP transfer */
35 static int pxe_single_fd = -1;
36
37 /** Block size for "single-file-only" PXE TFTP transfer */
38 static size_t pxe_single_blksize;
39
40 /** Current block index for "single-file-only" PXE TFTP transfer */
41 static unsigned int pxe_single_blkidx;
42
43 /** Length of a PXE-derived URI
44  *
45  * The "single-file-only" API calls use a filename field of 128 bytes.
46  * 256 bytes provides plenty of space for constructing the (temporary)
47  * full URI.
48  */
49 #define PXE_URI_LEN 256
50
51 /**
52  * Build PXE URI string
53  *
54  * @v uri_string        URI string to fill in
55  * @v ipaddress         Server IP address (in network byte order)
56  * @v port              Server port (in network byte order)
57  * @v filename          File name
58  * @v blksize           Requested block size, or 0
59  *
60  * The URI string buffer must be at least @c PXE_URI_LEN bytes long.
61  */
62 static void pxe_tftp_build_uri ( char *uri_string,
63                                  uint32_t ipaddress, unsigned int port,
64                                  const unsigned char *filename,
65                                  int blksize ) {
66         struct in_addr address;
67
68         /* This is a fix to make Microsoft Remote Install Services work (RIS) */
69 #warning "Overwrite DHCP filename"
70
71         address.s_addr = ipaddress;
72         if ( ! port )
73                 port = htons ( TFTP_PORT );
74         if ( ! blksize )
75                 blksize = TFTP_MAX_BLKSIZE;
76         tftp_set_request_blksize ( blksize );
77
78         snprintf ( uri_string, PXE_URI_LEN, "tftp://%s:%d%s%s",
79                    inet_ntoa ( address ), ntohs ( port ),
80                    ( ( filename[0] == '/' ) ? "" : "/" ), filename );
81 }
82
83 /**
84  * TFTP OPEN
85  *
86  * @v tftp_open                         Pointer to a struct s_PXENV_TFTP_OPEN
87  * @v s_PXENV_TFTP_OPEN::ServerIPAddress TFTP server IP address
88  * @v s_PXENV_TFTP_OPEN::GatewayIPAddress Relay agent IP address, or 0.0.0.0
89  * @v s_PXENV_TFTP_OPEN::FileName       Name of file to open
90  * @v s_PXENV_TFTP_OPEN::TFTPPort       TFTP server UDP port
91  * @v s_PXENV_TFTP_OPEN::PacketSize     TFTP blksize option to request
92  * @ret #PXENV_EXIT_SUCCESS             File was opened
93  * @ret #PXENV_EXIT_FAILURE             File was not opened
94  * @ret s_PXENV_TFTP_OPEN::Status       PXE status code
95  * @ret s_PXENV_TFTP_OPEN::PacketSize   Negotiated blksize
96  * @err #PXENV_STATUS_TFTP_INVALID_PACKET_SIZE Requested blksize too small
97  *
98  * Opens a TFTP connection for downloading a file a block at a time
99  * using pxenv_tftp_read().
100  *
101  * If s_PXENV_TFTP_OPEN::GatewayIPAddress is 0.0.0.0, normal IP
102  * routing will take place.  See the relevant
103  * @ref pxe_routing "implementation note" for more details.
104  *
105  * Because we support arbitrary protocols, most of which have no
106  * notion of "block size" and will return data in arbitrary-sized
107  * chunks, we cheat and pretend to the caller that the blocksize is
108  * always accepted as-is.
109  *
110  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
111  * value before calling this function in protected mode.  You cannot
112  * call this function with a 32-bit stack segment.  (See the relevant
113  * @ref pxe_x86_pmode16 "implementation note" for more details.)
114  * 
115  * @note According to the PXE specification version 2.1, this call
116  * "opens a file for reading/writing", though how writing is to be
117  * achieved without the existence of an API call %pxenv_tftp_write()
118  * is not made clear.
119  *
120  * @note Despite the existence of the numerous statements within the
121  * PXE specification of the form "...if a TFTP/MTFTP or UDP connection
122  * is active...", you cannot use pxenv_tftp_open() and
123  * pxenv_tftp_read() to read a file via MTFTP; only via plain old
124  * TFTP.  If you want to use MTFTP, use pxenv_tftp_read_file()
125  * instead.  Astute readers will note that, since
126  * pxenv_tftp_read_file() is an atomic operation from the point of
127  * view of the PXE API, it is conceptually impossible to issue any
128  * other PXE API call "if an MTFTP connection is active".
129  */
130 PXENV_EXIT_t pxenv_tftp_open ( struct s_PXENV_TFTP_OPEN *tftp_open ) {
131         char uri_string[PXE_URI_LEN];
132
133         DBG ( "PXENV_TFTP_OPEN" );
134
135         /* Guard against callers that fail to close before re-opening */
136         close ( pxe_single_fd );
137         pxe_single_fd = -1;
138
139         /* Construct URI */
140         pxe_tftp_build_uri ( uri_string, tftp_open->ServerIPAddress,
141                              tftp_open->TFTPPort, tftp_open->FileName,
142                              tftp_open->PacketSize );
143         DBG ( " %s", uri_string );
144
145         /* Open URI */
146         pxe_single_fd = open ( uri_string );
147         if ( pxe_single_fd < 0 ) {
148                 tftp_open->Status = PXENV_STATUS ( pxe_single_fd );
149                 return PXENV_EXIT_FAILURE;
150         }
151
152         /* Record parameters for later use */
153         pxe_single_blksize = tftp_open->PacketSize;
154         pxe_single_blkidx = 0;
155
156         tftp_open->Status = PXENV_STATUS_SUCCESS;
157         return PXENV_EXIT_SUCCESS;
158 }
159
160 /**
161  * TFTP CLOSE
162  *
163  * @v tftp_close                        Pointer to a struct s_PXENV_TFTP_CLOSE
164  * @ret #PXENV_EXIT_SUCCESS             File was closed successfully
165  * @ret #PXENV_EXIT_FAILURE             File was not closed
166  * @ret s_PXENV_TFTP_CLOSE::Status      PXE status code
167  * @err None                            -
168  *
169  * Close a connection previously opened with pxenv_tftp_open().  You
170  * must have previously opened a connection with pxenv_tftp_open().
171  *
172  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
173  * value before calling this function in protected mode.  You cannot
174  * call this function with a 32-bit stack segment.  (See the relevant
175  * @ref pxe_x86_pmode16 "implementation note" for more details.)
176  */
177 PXENV_EXIT_t pxenv_tftp_close ( struct s_PXENV_TFTP_CLOSE *tftp_close ) {
178         DBG ( "PXENV_TFTP_CLOSE" );
179
180         close ( pxe_single_fd );
181         pxe_single_fd = -1;
182         tftp_close->Status = PXENV_STATUS_SUCCESS;
183         return PXENV_EXIT_SUCCESS;
184 }
185
186 /**
187  * TFTP READ
188  *
189  * @v tftp_read                         Pointer to a struct s_PXENV_TFTP_READ
190  * @v s_PXENV_TFTP_READ::Buffer         Address of data buffer
191  * @ret #PXENV_EXIT_SUCCESS             Data was read successfully
192  * @ret #PXENV_EXIT_FAILURE             Data was not read
193  * @ret s_PXENV_TFTP_READ::Status       PXE status code
194  * @ret s_PXENV_TFTP_READ::PacketNumber TFTP packet number
195  * @ret s_PXENV_TFTP_READ::BufferSize   Length of data written into buffer
196  *
197  * Reads a single packet from a connection previously opened with
198  * pxenv_tftp_open() into the data buffer pointed to by
199  * s_PXENV_TFTP_READ::Buffer.  You must have previously opened a
200  * connection with pxenv_tftp_open().  The data written into
201  * s_PXENV_TFTP_READ::Buffer is just the file data; the various
202  * network headers have already been removed.
203  *
204  * The buffer must be large enough to contain a packet of the size
205  * negotiated via the s_PXENV_TFTP_OPEN::PacketSize field in the
206  * pxenv_tftp_open() call.  It is worth noting that the PXE
207  * specification does @b not require the caller to fill in
208  * s_PXENV_TFTP_READ::BufferSize before calling pxenv_tftp_read(), so
209  * the PXE stack is free to ignore whatever value the caller might
210  * place there and just assume that the buffer is large enough.  That
211  * said, it may be worth the caller always filling in
212  * s_PXENV_TFTP_READ::BufferSize to guard against PXE stacks that
213  * mistake it for an input parameter.
214  *
215  * The length of the TFTP data packet will be returned via
216  * s_PXENV_TFTP_READ::BufferSize.  If this length is less than the
217  * blksize negotiated via s_PXENV_TFTP_OPEN::PacketSize in the call to
218  * pxenv_tftp_open(), this indicates that the block is the last block
219  * in the file.  Note that zero is a valid length for
220  * s_PXENV_TFTP_READ::BufferSize, and will occur when the length of
221  * the file is a multiple of the blksize.
222  *
223  * The PXE specification doesn't actually state that calls to
224  * pxenv_tftp_read() will return the data packets in strict sequential
225  * order, though most PXE stacks will probably do so.  The sequence
226  * number of the packet will be returned in
227  * s_PXENV_TFTP_READ::PacketNumber.  The first packet in the file has
228  * a sequence number of one, not zero.
229  *
230  * To guard against flawed PXE stacks, the caller should probably set
231  * s_PXENV_TFTP_READ::PacketNumber to one less than the expected
232  * returned value (i.e. set it to zero for the first call to
233  * pxenv_tftp_read() and then re-use the returned s_PXENV_TFTP_READ
234  * parameter block for subsequent calls without modifying
235  * s_PXENV_TFTP_READ::PacketNumber between calls).  The caller should
236  * also guard against potential problems caused by flawed
237  * implementations returning the occasional duplicate packet, by
238  * checking that the value returned in s_PXENV_TFTP_READ::PacketNumber
239  * is as expected (i.e. one greater than that returned from the
240  * previous call to pxenv_tftp_read()).
241  *
242  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
243  * value before calling this function in protected mode.  You cannot
244  * call this function with a 32-bit stack segment.  (See the relevant
245  * @ref pxe_x86_pmode16 "implementation note" for more details.)
246  */
247 PXENV_EXIT_t pxenv_tftp_read ( struct s_PXENV_TFTP_READ *tftp_read ) {
248         userptr_t buffer;
249         ssize_t len;
250
251         DBG ( "PXENV_TFTP_READ to %04x:%04x",
252               tftp_read->Buffer.segment, tftp_read->Buffer.offset );
253
254         buffer = real_to_user ( tftp_read->Buffer.segment,
255                                 tftp_read->Buffer.offset );
256         len = read_user ( pxe_single_fd, buffer, 0, pxe_single_blksize );
257         if ( len < 0 ) {
258                 tftp_read->Status = PXENV_STATUS ( len );
259                 return PXENV_EXIT_FAILURE;
260         }
261         tftp_read->BufferSize = len;
262         tftp_read->PacketNumber = ++pxe_single_blkidx;
263
264         tftp_read->Status = PXENV_STATUS_SUCCESS;
265         return PXENV_EXIT_SUCCESS;
266 }
267
268 /**
269  * TFTP/MTFTP read file
270  *
271  * @v tftp_read_file                 Pointer to a struct s_PXENV_TFTP_READ_FILE
272  * @v s_PXENV_TFTP_READ_FILE::FileName          File name
273  * @v s_PXENV_TFTP_READ_FILE::BufferSize        Size of the receive buffer
274  * @v s_PXENV_TFTP_READ_FILE::Buffer            Address of the receive buffer
275  * @v s_PXENV_TFTP_READ_FILE::ServerIPAddress   TFTP server IP address
276  * @v s_PXENV_TFTP_READ_FILE::GatewayIPAddress  Relay agent IP address
277  * @v s_PXENV_TFTP_READ_FILE::McastIPAddress    File's multicast IP address
278  * @v s_PXENV_TFTP_READ_FILE::TFTPClntPort      Client multicast UDP port
279  * @v s_PXENV_TFTP_READ_FILE::TFTPSrvPort       Server multicast UDP port
280  * @v s_PXENV_TFTP_READ_FILE::TFTPOpenTimeOut   Time to wait for first packet
281  * @v s_PXENV_TFTP_READ_FILE::TFTPReopenDelay   MTFTP inactivity timeout
282  * @ret #PXENV_EXIT_SUCCESS                     File downloaded successfully
283  * @ret #PXENV_EXIT_FAILURE                     File not downloaded
284  * @ret s_PXENV_TFTP_READ_FILE::Status          PXE status code
285  * @ret s_PXENV_TFTP_READ_FILE::BufferSize      Length of downloaded file
286  *
287  * Downloads an entire file via either TFTP or MTFTP into the buffer
288  * pointed to by s_PXENV_TFTP_READ_FILE::Buffer.
289  *
290  * The PXE specification does not make it clear how the caller
291  * requests that MTFTP be used rather than TFTP (or vice versa).  One
292  * reasonable guess is that setting
293  * s_PXENV_TFTP_READ_FILE::McastIPAddress to 0.0.0.0 would cause TFTP
294  * to be used instead of MTFTP, though it is conceivable that some PXE
295  * stacks would interpret that as "use the DHCP-provided multicast IP
296  * address" instead.  Some PXE stacks will not implement MTFTP at all,
297  * and will always use TFTP.
298  *
299  * It is not specified whether or not
300  * s_PXENV_TFTP_READ_FILE::TFTPSrvPort will be used as the TFTP server
301  * port for TFTP (rather than MTFTP) downloads.  Callers should assume
302  * that the only way to access a TFTP server on a non-standard port is
303  * to use pxenv_tftp_open() and pxenv_tftp_read().
304  *
305  * If s_PXENV_TFTP_READ_FILE::GatewayIPAddress is 0.0.0.0, normal IP
306  * routing will take place.  See the relevant
307  * @ref pxe_routing "implementation note" for more details.
308  *
309  * It is interesting to note that s_PXENV_TFTP_READ_FILE::Buffer is an
310  * #ADDR32_t type, i.e. nominally a flat physical address.  Some PXE
311  * NBPs (e.g. NTLDR) are known to call pxenv_tftp_read_file() in real
312  * mode with s_PXENV_TFTP_READ_FILE::Buffer set to an address above
313  * 1MB.  This means that PXE stacks must be prepared to write to areas
314  * outside base memory.  Exactly how this is to be achieved is not
315  * specified, though using INT 15,87 is as close to a standard method
316  * as any, and should probably be used.  Switching to protected-mode
317  * in order to access high memory will fail if pxenv_tftp_read_file()
318  * is called in V86 mode; it is reasonably to expect that a V86
319  * monitor would intercept the relatively well-defined INT 15,87 if it
320  * wants the PXE stack to be able to write to high memory.
321  *
322  * Things get even more interesting if pxenv_tftp_read_file() is
323  * called in protected mode, because there is then absolutely no way
324  * for the PXE stack to write to an absolute physical address.  You
325  * can't even get around the problem by creating a special "access
326  * everything" segment in the s_PXE data structure, because the
327  * #SEGDESC_t descriptors are limited to 64kB in size.
328  *
329  * Previous versions of the PXE specification (e.g. WfM 1.1a) provide
330  * a separate API call, %pxenv_tftp_read_file_pmode(), specifically to
331  * work around this problem.  The s_PXENV_TFTP_READ_FILE_PMODE
332  * parameter block splits s_PXENV_TFTP_READ_FILE::Buffer into
333  * s_PXENV_TFTP_READ_FILE_PMODE::BufferSelector and
334  * s_PXENV_TFTP_READ_FILE_PMODE::BufferOffset, i.e. it provides a
335  * protected-mode segment:offset address for the data buffer.  This
336  * API call is no longer present in version 2.1 of the PXE
337  * specification.
338  *
339  * Etherboot makes the assumption that s_PXENV_TFTP_READ_FILE::Buffer
340  * is an offset relative to the caller's data segment, when
341  * pxenv_tftp_read_file() is called in protected mode.
342  *
343  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
344  * value before calling this function in protected mode.  You cannot
345  * call this function with a 32-bit stack segment.  (See the relevant
346  * @ref pxe_x86_pmode16 "implementation note" for more details.)
347  *
348  * @note Microsoft's NTLDR assumes that the filename passed in via
349  * s_PXENV_TFTP_READ_FILE::FileName will be stored in the "file" field
350  * of the stored DHCPACK packet, whence it will be returned via any
351  * subsequent calls to pxenv_get_cached_info().  Though this is
352  * essentially a bug in the Intel PXE implementation (not, for once,
353  * in the specification!), it is a bug that Microsoft relies upon, and
354  * so we implement this bug-for-bug compatibility by overwriting the
355  * filename stored DHCPACK packet with the filename passed in
356  * s_PXENV_TFTP_READ_FILE::FileName.
357  *
358  */
359 PXENV_EXIT_t pxenv_tftp_read_file ( struct s_PXENV_TFTP_READ_FILE
360                                     *tftp_read_file ) {
361         char uri_string[PXE_URI_LEN];
362         int fd;
363         userptr_t buffer;
364         size_t max_len;
365         ssize_t frag_len;
366         size_t len = 0;
367         int rc = -ENOBUFS;
368
369         DBG ( "PXENV_TFTP_READ_FILE" );
370
371         /* Construct URI */
372         pxe_tftp_build_uri ( uri_string, tftp_read_file->ServerIPAddress,
373                              tftp_read_file->TFTPSrvPort,
374                              tftp_read_file->FileName, 0 );
375         DBG ( " %s", uri_string );
376
377         DBG ( " to %08lx+%lx", tftp_read_file->Buffer,
378               tftp_read_file->BufferSize );
379
380         /* Open URI */
381         fd = open ( uri_string );
382         if ( fd < 0 ) {
383                 tftp_read_file->Status = PXENV_STATUS ( fd );
384                 return PXENV_EXIT_FAILURE;
385         }
386
387         /* Read file */
388         buffer = phys_to_user ( tftp_read_file->Buffer );
389         max_len = tftp_read_file->BufferSize;
390         while ( max_len ) {
391                 frag_len = read_user ( fd, buffer, len, max_len );
392                 if ( frag_len <= 0 ) {
393                         rc = frag_len;
394                         break;
395                 }
396                 len += frag_len;
397                 max_len -= frag_len;
398         }
399
400         close ( fd );
401         tftp_read_file->BufferSize = len;
402         tftp_read_file->Status = PXENV_STATUS ( rc );
403         return ( rc ? PXENV_EXIT_FAILURE : PXENV_EXIT_SUCCESS );        
404 }
405
406 /**
407  * TFTP GET FILE SIZE
408  *
409  * @v tftp_get_fsize                 Pointer to a struct s_PXENV_TFTP_GET_FSIZE
410  * @v s_PXENV_TFTP_GET_FSIZE::ServerIPAddress   TFTP server IP address
411  * @v s_PXENV_TFTP_GET_FSIZE::GatewayIPAddress  Relay agent IP address
412  * @v s_PXENV_TFTP_GET_FSIZE::FileName  File name
413  * @ret #PXENV_EXIT_SUCCESS             File size was determined successfully
414  * @ret #PXENV_EXIT_FAILURE             File size was not determined
415  * @ret s_PXENV_TFTP_GET_FSIZE::Status  PXE status code
416  * @ret s_PXENV_TFTP_GET_FSIZE::FileSize        File size
417  *
418  * Determine the size of a file on a TFTP server.  This uses the
419  * "tsize" TFTP option, and so will not work with a TFTP server that
420  * does not support TFTP options, or that does not support the "tsize"
421  * option.
422  *
423  * The PXE specification states that this API call will @b not open a
424  * TFTP connection for subsequent use with pxenv_tftp_read().  (This
425  * is somewhat daft, since the only way to obtain the file size via
426  * the "tsize" option involves issuing a TFTP open request, but that's
427  * life.)
428  *
429  * You cannot call pxenv_tftp_get_fsize() while a TFTP or UDP
430  * connection is open.
431  *
432  * If s_PXENV_TFTP_GET_FSIZE::GatewayIPAddress is 0.0.0.0, normal IP
433  * routing will take place.  See the relevant
434  * @ref pxe_routing "implementation note" for more details.
435  *
436  * On x86, you must set the s_PXE::StatusCallout field to a nonzero
437  * value before calling this function in protected mode.  You cannot
438  * call this function with a 32-bit stack segment.  (See the relevant
439  * @ref pxe_x86_pmode16 "implementation note" for more details.)
440  * 
441  * @note There is no way to specify the TFTP server port with this API
442  * call.  Though you can open a file using a non-standard TFTP server
443  * port (via s_PXENV_TFTP_OPEN::TFTPPort or, potentially,
444  * s_PXENV_TFTP_READ_FILE::TFTPSrvPort), you can only get the size of
445  * a file from a TFTP server listening on the standard TFTP port.
446  * "Consistency" is not a word in Intel's vocabulary.
447  */
448 PXENV_EXIT_t pxenv_tftp_get_fsize ( struct s_PXENV_TFTP_GET_FSIZE
449                                     *tftp_get_fsize ) {
450         char uri_string[PXE_URI_LEN];
451         int fd;
452         ssize_t size;
453
454         DBG ( "PXENV_TFTP_GET_FSIZE" );
455
456         /* Construct URI */
457         pxe_tftp_build_uri ( uri_string, tftp_get_fsize->ServerIPAddress,
458                              0, tftp_get_fsize->FileName, 0 );
459         DBG ( " %s", uri_string );
460
461         /* Open URI */
462         fd = open ( uri_string );
463         if ( fd < 0 ) {
464                 tftp_get_fsize->Status = PXENV_STATUS ( fd );
465                 return PXENV_EXIT_FAILURE;
466         }
467
468         /* Determine size */
469         size = fsize ( fd );
470         close ( fd );
471         if ( size < 0 ) {
472                 tftp_get_fsize->Status = PXENV_STATUS ( size );
473                 return PXENV_EXIT_FAILURE;
474         }
475
476         tftp_get_fsize->FileSize = size;
477         tftp_get_fsize->Status = PXENV_STATUS_SUCCESS;
478         return PXENV_EXIT_SUCCESS;
479 }