TFTP

The TFTP client and server are described in tftp_support.h;

The TFTP client has and new and an older, deprecated, API. The new API works for both IPv4 and IPv6 where as the deprecated API is IPv4 only.

The new API is as follows:

int tftp_client_get(const char * const filename,
		    const char * const server,
		    const int port,
		    char *buf,
		    int len,
		    const int mode,
		    int * const err);

int tftp_client_put(const char * const filename,
		    const char * const server,
		    const int port,
		    const char *buf,
		    int len,
		    const int mode,
		    int *const err);

Currently server can only be a numeric IPv4 or IPv6 address. The resolver is currently not used, but it is planned to add this feature (patches welcome). If port is zero the client connects to the default TFTP port on the server. Otherwise the specified port is used.

The deprecated API is:

int tftp_get(const char * const filename, 
             const struct sockaddr_in * const server, 
             char * buf, 
             int len, 
             const int mode, 
             int * const error);

int tftp_put(const char * const filename, 
             const struct sockaddr_in * const server, 
             const char * buffer, 
             int len, 
             const int mode, 
             int * const err);

The server should contain the address of the server to contact. If the sin_port member of the structure is zero the default TFTP port is used. Otherwise the specified port is used.

Both API's report errors in the same way. The functions return a value of -1 and *err will be set to one of the following values:

#define	TFTP_ENOTFOUND   1   /* file not found */
#define	TFTP_EACCESS     2   /* access violation */
#define	TFTP_ENOSPACE    3   /* disk full or allocation exceeded */
#define	TFTP_EBADOP      4   /* illegal TFTP operation */
#define	TFTP_EBADID      5   /* unknown transfer ID */
#define	TFTP_EEXISTS     6   /* file already exists */
#define	TFTP_ENOUSER     7   /* no such user */
#define TFTP_TIMEOUT     8   /* operation timed out */
#define TFTP_NETERR      9   /* some sort of network error */
#define TFTP_INVALID    10   /* invalid parameter */
#define TFTP_PROTOCOL   11   /* protocol violation */
#define TFTP_TOOLARGE   12   /* file is larger than buffer */

If there are no errors the return value is the number of bytes transfered.

The server is more complex. It requires a filesystem implementation to be supplied by the user, and attached to the tftp server by means of a vector of function pointers:

struct tftpd_fileops {
             int (*open)(const char *, int);
             int (*close)(int);
             int (*write)(int, const void *, int);
             int (*read)(int, void *, int);
};

These functions have the obvious semantics. The structure describing the filesystem is an argument to the tftpd_start:

int tftp_start(int port,
               struct tftpd_fileops *ops);

The first argument is the port to use for the server. If this port number is zero, the default TFTP port number will be used. The return value from tftpd_start is a handle which can be passed to tftpd_stop. This will kill the tftpd thread. Note that this is not a clean shutdown. The thread will simply be killed. tftpd_stop will attempt to close the sockets the thread was listening on and free some of its allocated memory. But if the thread was actively transferreing data at the time tftpd_stop is called, it is quite likely some memory and a socket will be leaked. Use this function with caution (or implement a clean shutdown and please contribute the code back :-).

There are two CDL configuration options that control how many servers on how many different ports tftp can be started. CYGSEM_NET_TFTPD_MULTITHREADED, when enabled, allows multiple tftpd threads to operate on the same port number. With only one thread, while the thread is active transferring data, new requests for transfers will not be served until the active transfer is complete. When multiple threads are started on the same port, multiple transfers can take place simultaneous, up to the number of threads started. However a semaphore is required to synchronise the threads. This semaphore is required per port. The CDL option CYGNUM_NET_TFTPD_MULTITHREADED_PORTS controls how many different port numbers multithreaded servers can service.

If CYGSEM_NET_TFTPD_MULTITHREADED is not enabled, only one thread may be run per port number. But this removes the need for a semaphore and so CYGNUM_NET_TFTPD_MULTITHREADED_PORTS is not required and unlimited number of ports can be used.

It should be noted that the TFTPD does not perform any form of file locking. When multiple servers are active, it is assumed the underlying filesystem will refuse to open the same file multiple times, operate correctly with simultaneous read/writes to the same file, or if you are unlucky, corrupt itself beyond all repair.

When IPv6 is enabled the tftpd thread will listen for requests from both IPv4 and IPv6 addresses.

As discussed in the description of the tftp_server_test above, an example filesystem is provided in net/common/VERSION/src/tftp_dummy_file.c for use by the tftp server test. The dummy filesystem is not a supported part of the network stack, it exists purely for demonstration purposes.