Doxygenation
authorMichael Brown <mcb30@etherboot.org>
Wed, 1 Jun 2005 13:28:07 +0000 (13:28 +0000)
committerMichael Brown <mcb30@etherboot.org>
Wed, 1 Jun 2005 13:28:07 +0000 (13:28 +0000)
src/proto/tftp.c

index e5bf5a8..5370644 100644 (file)
 /**
  * Process a TFTP block
  *
+ * @v state                    TFTP transfer state
+ * @v tftp_state::block                Last received data block
+ * @v tftp_state::blksize      Transfer block size
+ * @v data                     The data block to process
+ * @v buffer                   The buffer to fill with the data
+ * @ret True                   Block processed successfully
+ * @ret False                  Block not processed successfully
+ * @ret tftp_state::block      Incremented if applicable
+ * @ret *eof                   End-of-file marker
+ * @err #PXENV_STATUS_TFTP_INVALID_PACKET_SIZE Packet is too large
+ * @err other                  As returned by fill_buffer()
+ *
+ * Process a TFTP DATA packet that has been received.  If the data
+ * packet is the next data packet in the stream, its contents will be
+ * placed in the #buffer and tftp_state::block will be incremented.
+ * If the packet is the final packet, end-of-file will be indicated
+ * via #eof.
+ *
+ * If the data packet is a duplicate, then process_tftp_data() will
+ * still return True, though nothing will be done with the packet.  A
+ * False return value always indicates an error that should abort the
+ * transfer.
  */
 static inline int process_tftp_data ( struct tftp_state *state,
                                      struct tftp_data *data,
@@ -32,7 +54,8 @@ static inline int process_tftp_data ( struct tftp_state *state,
        if ( blksize > state->blksize ) {
                DBG ( "TFTP: oversized block size %d (max %d)\n",
                      blksize, state->blksize );
-               return 1;
+               errno = PXENV_STATUS_TFTP_INVALID_PACKET_SIZE;
+               return 0;
        }
        /* Place block in the buffer */
        if ( ! fill_buffer ( buffer, data->data, state->block * state->blksize,
@@ -50,9 +73,21 @@ static inline int process_tftp_data ( struct tftp_state *state,
 /**
  * Download a file via TFTP
  *
+ * @v server                           TFTP server
+ * @v file                             File name
+ * @v buffer                           Buffer into which to load file
+ * @ret True                           File was downloaded successfully
+ * @ret False                          File was not downloaded successfully
+ * @err #PXENV_STATUS_TFTP_UNKNOWN_OPCODE Unknown type of TFTP block received
+ * @err other                          As returned by tftp_open()
+ * @err other                          As returned by tftp_process_opts()
+ * @err other                          As returned by tftp_ack()
+ * @err other                          As returned by tftp_process_data()
+ *
+ * Download a file from a TFTP server into the specified buffer.
  */
-int tftp ( char *url __unused, struct sockaddr_in *server, char *file,
-          struct buffer *buffer ) {
+static int tftp ( char *url __unused, struct sockaddr_in *server, char *file,
+                 struct buffer *buffer ) {
        struct tftp_state state;
        union tftp_any *reply;
        int eof = 0;