path: root/cpukit/include/rtems/tftp.h

/* SPDX-License-Identifier: BSD-2-Clause */

/**
 * @file
 *
 * @ingroup RTEMSImplTFTPFS
 *
 * @brief This header file provides interfaces and functions used to
 *   implement the TFTP file system.
 *
 * This file declares the public functions of the Trivial File
 * Transfer Protocol (TFTP) file system.
 */

/*
 * Copyright (C) 1998 W. Eric Norum <eric@norum.ca>
 * Copyright (C) 2022 embedded brains GmbH (http://www.embedded-brains.de)
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef _RTEMS_TFTP_H
#define _RTEMS_TFTP_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>
#include <rtems/fs.h>

/**
 * @brief Do not call directly, use mount().
 *
 * @ingroup RTEMSImplTFTPFS
 *
 * Filesystem Mount table entry.
 */
int rtems_tftpfs_initialize(
  rtems_filesystem_mount_table_entry_t *mt_entry,
  const void *data
);

/**
 * @defgroup RTEMSAPITFTPFS Trivial File Transfer Protocol (TFTP) API
 *
 * @ingroup RTEMSAPIIO
 *
 * @brief The TFTP client library provides an API to read files from and
 *   to write files to remote servers using the Trivial File Transfer
 *   Protocol (TFTP).
 *
 * See the _RTEMS Filesystem Design Guide_ Chapter _Trivial FTP Client
 * Filesystem_.
 *
 * Usage as TFTP File System
 * =========================
 *
 * To open `/bootfiles/image` on `hostname` for reading:
 *
 *     fd = open ("/TFTP/hostname:bootfiles/image", O_RDONLY);
 *
 * The `TFTP` is the mount path and the `hostname` must be
 *
 * + an IPv4 address (like `127.0.0.1`) or
 * + the (full-qualified) name of an IPv4 host (acceptable to
 *  `gethostbyname()`)
 *
 * IPv6 is currently not supported. `bootfiles/image` is a path on the
 * TFTP server `hostname` where the file (here `image`) can be found.
 *
 * Usage of TFTP Client
 * ====================
 *
 * The pseudo-code below shows the principal usage for reading a file.
 *
 * @code
 *   int res;
 *   ssize_t bytes;
 *   void *tftp_handle;
 *   tftp_net_config config;
 *   const size_t buffer_size = 4000;
 *   char data_buffer[buffer_size];
 *
 *   tftp_initialize_net_config( &config );
 *   config.options.window_size = 1; // Set desired config values
 *
 *   res = tftp_open(
 *     "127.0.0.1",
 *     "filename.txt",
 *     true, // is_for_reading
 *     &config,
 *     &tftp_handle
 *   );
 *
 *   if ( res != 0 || tftp_handle == NULL ) {
 *     // Error
 *   }
 *
 *   // Use tftp_read() (probably in a loop) ...
 *   bytes = tftp_read(
 *     tftp_handle,
 *     data_buffer,
 *     buffer_size
 *   );
 *   // ... or use tftp_write() instead when the file is open for writing.
 *
 *   res = tftp_close( tftp_handle );
 *
 *   if ( res != 0 ) {
 *     // Error ... check! Especially when writing!
 *   }
 * @endcode
 *
 * @{
 */

/*
 * The functions below use of the TFTP client library standalone
 * - i.e. without going through the file system.
 */

/**
 * @brief This block size meets RFC 1350 and avoids the sending of
 *   the `blksize` option to the TFTP server.
 */
#define TFTP_RFC1350_BLOCK_SIZE 512

/**
 * @brief This window size avoids the sending of the `windowsize`
 *   option to the TFTP server.
 *
 * This effectively mimics the operation defined in RFC 1350 which
 * does not know any window size.
 */
#define TFTP_RFC1350_WINDOW_SIZE 1

/**
 * @brief This block size is suggested in RFC 2348 and is used as
 *   default if no different block size is provided.
 */
#define TFTP_DEFAULT_BLOCK_SIZE 1456

/**
 * @brief This window size is suggested in RFC 2348 and is used as
 *   default if no different window size is provided.
 */
#define TFTP_DEFAULT_WINDOW_SIZE 8

/**
 * @brief This structure represents TFTP options negotiated between
 *   client and server.
 *
 * RFC 2347 is the basis for the TFTP option.
 */
typedef struct tftp_options {
  /**
   * @brief This member represents the desired size of a data block.
   *
   * The TFTP blocksize option is introduced in RFC 2348.  It defines the
   * number of octets in the data packets transferred.  Valid values
   * range between 8 and 65464 octets, inclusive.  Values larger
   * than 1468 may cause packet fragmentation over standard Ethernet.
   * A value of 512 will prevent this option from being sent to
   * the server.
   *
   * The default value is 1456.
   */
  uint16_t block_size;

  /**
   * @brief This member represents the desired size of a window.
   *
   * The TFTP windowsize option is introduced in RFC 7440.  It defines the
   * number of data packets send before the receiver must send an
   * acknowledgment packet.  Valid values range between 1 and 65535
   * packets, inclusive.  Simple TFTP servers usually do not support this
   * option.  This option may negatively contribute to network
   * congestion.  This can be avoided by using a window size of 1.
   * A value of 1 will prevent this option from being sent to
   * the server.
   *
   * The default value is 8.
   */
  uint16_t window_size;
} tftp_options;

/**
 * @brief This structure represents configuration value used by the TFTP
 *   client.
 *
 * As defaults the values suggested in RFC 7440 are used.
 */
typedef struct tftp_net_config {
  /**
   * @brief This member defines how many attempts are made to send a
   *   network packet to the server.
   *
   * Repetitions occur when the server does not response to a packet
   * send by the client within a timeout period.  When the here defined
   * number of repetitions is reached and the server does still not
   * respond, the connection is considered broken and the file transfer
   * is ended with an error.
   *
   * The default value is 6.
   */
  uint16_t retransmissions;

  /**
   * @brief This member defines the port on which the server is listening
   *   for incoming connections.
   *
   * The default port number is 69.
   */
  uint16_t server_port;

  /**
   * @brief This member defines the maximum time in milliseconds the
   *   client waits for an answer packet from the server.
   *
   * If the time out is exceeded, the client will re-transmit the last
   * packet it send to the server.  In case @c window_size is larger one,
   * several packets may subject to re-transmission.
   *
   * Note that this timeout applies only after the first re-transmission
   * of a packet. The timeout till the first re-transmission is
   * @c first_timeout.
   *
   * The default value is 1000ms.
   */
  uint32_t timeout;

  /**
   * @brief This member defines the maximum time in milliseconds the
   *   client waits for the first answer packet from the server.
   *
   * The @c first_timeout is used instead of the regular @c timeout
   * for the first wait-period directly after the client sends a packet
   * for the first time to the server.  That is, this is the timeout
   * of the first re-transmission.  For any following re-transmissions
   * of the current packet the regular @c timeout is used.
   *
   * The default value is 400ms.
   */
  uint32_t first_timeout;

  /**
   * @brief This member represents the options to be sent to the server.
   *
   * These option values are sent to the server.  Yet, the server may
   *
   *   + ignore one or all options
   *   + ask the client to use a different value for an option
   *   + reject the whole request with an error
   *
   * If the server rejects a request with options, the current client
   * implementation will automatically send a second request without
   * options.  Hence, the user should be aware that the actual file
   * transfer may not use the option values specified here.
   */
  tftp_options options;
} tftp_net_config;

/**
 * @brief Set all members of a @c tftp_net_config structure to their
 *   default values.
 *
 * @param config references a @c tftp_net_config structure.
 *   The values are set to the defaults defined in
 *   @ref tftp_net_config "`type tftp_net_config`".
 */
void tftp_initialize_net_config(
  tftp_net_config *config
);

/**
 * @brief Opens and starts a TFTP client session to read or write a
 *   single file.
 *
 * This directive resolves the hostname or IP address, establishes a connection
 * to the TFTP server and initiates the data transfer.  It will not return
 * before an error is encountered or the TFTP server has responded to the
 * read or write request with a network packet.
 *
 * TFTP uses timeouts (of unspecified length).  It does not know keep-alive
 * messages.  If the client does not respond to the server in due time,
 * the server sets the connection faulty and drops it.  To avoid this
 * the user of this code must read or write enough data fast enough.
 *
 * "Enough data" means at least so much data which fills a single data
 * packet or all packets of a window if windows are used.  The data
 * can be read or written in anything from one single large chunk to
 * byte-by-byte pieces.  The point is, one cannot pause the reading
 * or writing for longer periods of time.
 *
 * @param hostname is the IPv4 address as string or the name of the TFTP
 *   server to connect to.
 * @param path is the pathname at the TFTP server side of the file to
 *   read or write.  According to RFC 1350 the path must be in
 *   NETASCII.  This is ASCII as defined in "USA Standard Code for
 *   Information Interchange" with the modifications specified in "Telnet
 *   Protocol Specification".
 * @param is_for_reading indicated whether the file is to be read or written.
 *   A value of @c true indicates that the file is intended to be read from
 *   the server.  A value of @c false indicates that the file is to be
 *   written to the server.
 * @param config either references a structure defining the configuration
 *   values for this file transfer or is @c NULL.  If it is @c NULL, default
 *   configuration values are used.  See @ref tftp_net_config
 *   "type tftp_net_config" for a description and the defaults values.
 *   This function copies the data so that the memory pointed to by
 *   @c config can be used for other purposes after the call returns.
 * @param[out] tftp_handle references a place where a handle of the connection
 *   can be stored.  On success a pointer to a handle is stored.  On failure
 *   (return value other than 0) a @c NULL pointer is stored.  This handle
 *   must be provided to all further calls to @c tftp_read(),
 *   @c tftp_write(), and @c tftp_close().
 *
 *   When this directive stores a non-NULL pointer in this place, a call
 *   to @c tftp_close() is mandatory to release allocated resources.
 *   This parameter cannot be @c NULL.
 *
 * @retval 0 When the client session was opened successfully.
 * @return Returns a POSIX @c errno value in case an error occurred.
 */
int tftp_open(
  const char  *hostname,
  const char  *path,
  bool   is_for_reading,
  const tftp_net_config *config,
  void **tftp_handle
);

/**
 * @brief Read data from a TFTP server.
 *
 * This directive attempts to read data from a TFTP connection open for
 * reading.
 *
 * Upon success, the buffer is always filled with @c count bytes of received
 * data with the exception when the end of the file has been reached.
 *
 * TFTP cannot recover from errors.  Once an error is reported, the
 * connection must be and can only be closed.
 *
 * @param tftp_handle is the reference returned by a call to tftp_open().
 *   The file must be opened for reading.
 * @param[out] buffer references a memory area into which the received
 *   data is written.
 * @param count defines the size of the @c buffer in bytes.
 *
 * @retval 0 The end of the file has been reached.  There is no more data.
 * @return If greater or equal to 0, returns the number of bytes written
 *   into the buffer.  If the return value is negative, an error occurred.
 *   In this case the negated value is a POSIX @c errno value.
 */
ssize_t tftp_read(
  void   *tftp_handle,
  void   *buffer,
  size_t  count
);

/**
 * @brief Write data to a TFTP server.
 *
 * This directive attempts to write data to a TFTP connection open for
 * writing.
 *
 * On a successful call, all data in the @c buffer will be used.  Yet, this
 * does not imply that all data is actually sent.  This depends on
 * whether a whole data packet or window can be filled.
 *
 * TFTP cannot recover from errors.  Once an error is reported, the connection
 * must be and can only be closed.
 *
 * @param tftp_handle is the reference returned by a call to tftp_open().
 *   The file must be opened for writing.
 * @param buffer references a memory area which contains the data to be
 *   sent.
 * @param count defines the size of the data in @c buffer in bytes.
 *
 * @return If greater or equal to 0, returns the number of bytes used
 *   from the buffer.  The value is always @c count on a successful call.
 *   If the return value is negative, an error occurred.  In this case
 *   the negated value is a POSIX @c errno value.
 */
ssize_t tftp_write(
  void       *tftp_handle,
  const void *buffer,
  size_t      count
);

/**
 * @brief Close a TFTP client connection.
 *
 * This directive sends all data which are still stored in a write buffer
 * to the server (if any), tells the server that the connection ends (if
 * required by RFC 1350) and releases any resources allocated at the
 * client side.
 *
 * @note Especially, when writing a file to the server, the return
 * code of `tftp_close()` should be checked.  Invoking
 * `tftp_close()` triggers the sending of the last -- not
 * completely filled -- data block.  This may fail the same way as any
 * `tftp_write()` may fail.  Therefore, an error returned by
 * `tftp_close()` likely indicates that the file was not
 * completely transferred.
 *
 * @param tftp_handle is the reference returned by a call to tftp_open().
 *   If this parameter is @c NULL, the directive call is a no-op.
 *
 * @retval 0 When the client session was closed successfully.
 * @return Returns a POSIX @c errno value in case an error occurred.
 */
int tftp_close(
  void *tftp_handle
);

/** @} */

#ifdef __cplusplus
}
#endif

#endif