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