Download User Manual

 Download Sample Source Code

HS TFTP for Embedded Systems v1.2
with integrated UDP/IP stack

 ORDER NOW

 Contacts Us

APPLICATIONS

Along with XMODEM or as an alternative, TFTP is often used in embedded devices and appliances for the purpose of software and / or configuration upgrade or retrieval.

TFTP / UDP / IP / ARP Features

TFTP server and client
Default 512 packet size
Concurrent server sessions
UDP session multiplexing
UDP encapsulation
UDP checksum protection
Minimum required IP implementation
NO Fragmentation or Re-assembly
Maintains ARP table
Resolves IP to MAC addresses
Generates ARP requests
Generates ARP replies

HS TFTP STATISTICS

Brief summary of api

overview

HS TFTP is a software library in C (supplied with full source code) which implements Trivial File Transfer Protocol (TFTP) over UDP/IP according to RFC 1350.

HS TFTP includes integrated UDP/IP stack necessary to transport TFTP protocol and is ideal self-contained solution for embedded systems, which may not otherwise have its own UDP/IP layer. Current Version of HS TFTP supports Big-endian memory model only

HS TFTP is supplied in a form of uncompiled ANSI C source code and would require minimal integration effort by the customer, assisted by Hillstone Software after sales support.

The use of HS TFTP software library is royalty free. Here are The Terms of License  

SOFTWARE ARCHITECTURE

In detail, HS TFTP for Embedded Systems consists of the following components:

target system requirements

Hardware Requirements:
Target System must have physical ethernet interface
Target System memory model must be Big-endian
RAM requirements: With default number of contexts 10, approx 200 kilobytes of RAM is required in total.
Flash / ROM / Code size requirements: code size of HS TFTP depends on target platform and on used compiler. As an rough guide, when compiled for Power Quicc MPC860 architecture, the code size is approx 115 kilobytes

Software Requirements:  
HS TFTP uses the following standard C libraries: string.h; malloc.h; stdio.h; ctype.h
 

POINTS OF INTEGRATION

Ethenet Frame transmission and Reception: To transmit an ethernet frame, HS TFTP calls EthTransmitFrame external function. This function would have to be replaced with whatever function is available for frame transmission over ethernet

When an ethernet frame is received, the function HsEthernetReceivePacket in HsIp.c is called. This function call will have to be made from existing ethernet driver software at a time when an ethernet packet is received.

Timers: HS TFTP uses timer callbacks in order to start and stop timers. The timer callbacks will need to call existing timer start, stop and timer expired functions available on target system

Timers: Flash file open (create), read and write functions: HS TFTP calls FLASHOpen, FLASHCLose, FLASHRead and FLASHWrite functions to perform operations on files. These function calls will have to be replaced to calls to existing file system functions.
 

MODEL OF OPERATION

The application layer initialises HS TFTP module, providing interface callbacks for the services used by HS TFTP protocol module: timer management, memory management, file operations and event callbacks. This architecture makes it easy to port HS TFTP protocol module to any environment.

TFTP module handles all protocol information flow, error recovery, acknowledgements, timeouts and so on. When it is appropriate to send next block of data HS TFTP will get next memory block from user application. Similarly, when data has been received HS TFTP module will get the next block of memory from user application to store data into.

At a lower layer HS TFTP interfaces to HS UDP module which provides UDP transport and session multiplexing services. In turn HS UDP talks to HS IP module which offers IP datagram transmission and reception service. HS IP calls HS ARP module to resolve IP address to MAC address and also communicates directly with Ethernet driver on target system.

SOFTWARE LICENSE TERMS

Extract from
HS TFTP for Embedded System v1.2
User Manual

1         HS TFTP API

1.1      HsTftpInit

Declaration:
extern int HsTftpInit(tftp_init_t *init);

Summary:
This function initialises HS TFTP Library and must be called first before any other functions are called. Init structure contains function pointers which must be initialised with function addresses in application layer. HS TFTP module will call these functions when it needs to manage timers and memory.

Parameters:
hs_tftp_init_t *init - Pointer to initialisation structure, defined as follows: 

Return values:

Sample usage:

// local ip address
static unsigned char our_ip_addr[] = "10.1.1.9";

/*
 * initiase TFTP library
 */
int init_tftp_library(void)
{
          tftp_init_t init = {0};
          int      rc; 

          memcpy(init.local_ip_addr_str, our_ip_addr, strlen(our_ip_addr));
          init.get_tx_buffer      = tftp_get_buf_tx_cb;
          init.get_rx_buffer      = tftp_get_buf_rx_cb;
          init.start_timer_fn     = tftp_start_timer_cb;
          init.stop_timer_fn      = hs_tftp_stop_timer_cb;         

          rc = HsTftpInit(&init);

          if (rc == HS_TFTP_RC_OK)
                   tftp_initialised = 1;

           return rc;
}

1.2      HsTftpDestroy

Declaration:
extern void HsTftpDestroy(void); 

Summary:
De-allocates resources and closes HS TFTP services.

Parameters:
None 

Return values:
None

Sample usage: 

HsTftpDestroy();

1.3      HsTftpStartServer

Declaration:
extern int HsTftpStartServer(
          hs_tftp_srv_ev_fn_t *callback_fn,            // event callback (used for server mode)
          unsigned short         tftp_port                 // initial TFTP port of server
);

Summary:
Starts server operation of HS TFTP module.

Parameters: 
unsigned short tftp_port – UDP port number the HS TFTP module listens for incoming TFTP client commands, recommended default value is 69.

 hs_tftp_srv_ev_fn_t *callback_fn – function pointer to callback function in application layer which receives events related to the status of the server operations:

typedef long hs_tftp_srv_ev_fn_t(long handle, int ev_code, long arg1, long arg2);

handle – currently unused
ev_code – one of the following values:
HS_TFTP_EV_WRITE_REQ – write request received from remote TFTP client (client wants to send file)
Arg1 – pointer to null terminated filename string
Arg2 – 32 bit remote IP address (address of TFTP client sending this request)

HS_TFTP_EV_READ_REQ - read request received from remote TFTP client (client wants to get file)
Arg1 – pointer to null terminated filename string
Arg2 – 32 bit remote IP address (address of TFTP client sending this request) 

Return values:

Sample usage:

/*
 * Event calback from TFTP library (server mode)
 */
long hs_tftp_ev_server_handler(long handle, int ev_code, long arg1, long arg2)
{
            unsigned char *file;

            if (!tftp_initialised)
                        return 0; 

            if (!handle)
                        return 0; 

            switch (ev_code)
            {
            case HS_TFTP_EV_WRITE_REQ:
                        file = (unsigned char *)arg1;
                        process_file_write_request(file, arg2);
                        break; 

            case HS_TFTP_EV_READ_REQ:
                        file = (unsigned char *)arg1;
                        process_file_read_request(file, arg2);
                        break;
            }

            return 0;
}

 /* Start server mode */
void StartServer(void)
{
            int rc;

            if (!tftp_initialised)
            {
                        rc = init_tftp_library();
                        if (rc != HS_TFTP_RC_OK)
                        {
                                    printf("HsTFTP init failed. Error %d\n", rc);      
                                    return;
                        }
            }           

            if (!server_started)
            {
                        rc = HsTftpStartServer(hs_tftp_ev_server_handler, TFTP_PORT);
                        if (rc != HS_TFTP_RC_OK)
                        {                     
                                    printf("Server failed to start. HS TFTP Error: %d\n", rc);
                                    return;
                        }

                        server_started = TRUE;
            }
            else
            {
                        printf("Server mode already running\n");
                        return;
            } 

            printf("Server mode started OK\n");
}

1.4      HsTftpServerStartReceive

Declaration:

extern
int HsTftpServerStartReceive(       
          hs_tftp_ev_fn_t       *callback_fn,  // event callback (used for indication of completion or error)
          long                       *handle,        // Connection handle returned after transfer initiated
          long                       user_handle); // upper layer context handle 

Summary:
Start receiving requested file from remote peer (in Server mode). This function is called in response to HS_TFTP_EV_WRITE_REQ event, which occurs when a write request for a file is received from remote TFTP client

Parameters:
hs_tftp_ev_fn_t *callback_fn – function pointer to a callback function in application (user) layer code which receives notifications related to this transfer session.

typedef long hs_tftp_ev_fn_t(long handle, int ev_code, long arg1, long arg2);
handle – application layer handle
ev_code – event, one of the following:
HS_TFTP_EV_ERR_TMOUT – session timed out and closed
HS_TFTP_RX_COMPLETE – receive transfer completed successfully
Arg1 and arg2 are currently unused

long *handle – pointer to long variable to received TFTP module connection handle after file transfer is initiated.

long user_handle – application layer context handle. This handle is saved into corresponding TFTP session context and is returned unchanged as a parameter in various notification callbacks from HS TFTP to application layer code.

Return values: 

Sample usage:

 /* server mode - process file write request */
void process_file_write_request(unsigned char *filename,  long arg2)
{
          int                         rc;
          unsigned char          ipstr[20] = {0};
          server_conn_ctx_t *pCtx;         

          HsSockInetNtoa(arg2, ipstr);

          printf("file write request from (%s) %s\n", ipstr, filename);

          pCtx = tftp_alloc_srvconn_ctx();
          if (!pCtx)
          {
                   printf("rejected: no free contexts\n");
                   HsTftpRejectRq(HS_TFTP_EV_WRITE_REQ,
                          HS_TFTP_SERVER_ERR_USER, "no free contexts");

                   return;
          } 

          pCtx->hFile = FLASHOpen(filename, "w");
          if (!pCtx->hFile)
          {
                   printf("rejected: file open error\n"); 
                   tftp_free_srvconn_ctx(pCtx);                  

                   /* Reject request */
                   HsTftpRejectRq(HS_TFTP_EV_WRITE_REQ, HS_TFTP_SERVER_ERR_FIO, NULL);
                   return;
          } 

          pCtx->is_server_session = TRUE;
          pCtx->is_send = FALSE;

          tftp_add_srvconn(pCtx);

          rc = HsTftpServerStartReceive(hs_tftp_server_ev_handler, &pCtx->tftp_handle, (long)pCtx);
          if (rc != HS_TFTP_RC_OK)
          {
                   printf("Server Start Receive failed RC (%u)\n", rc);
                   hs_tftp_cleanup_ctx(pCtx);
                   return;
          }

           printf("Server receive transfer started\n");
}

1.5      HsTftpServerStartSend

Declaration:
extern int HsTftpServerStartSend(
          hs_tftp_ev_fn_t       *callback_fn,  // event callback (used for infication of completion or error)
          long                       *handle,        // Connection handle returned after transfer initiated
          long                       user_handle); // upper layer context handle

Summary:
Start sending requested file to remote peer (in Server mode). This function is called in response to HS_TFTP_EV_READ_REQ event, which occurs when a read request for a file is received from remote TFTP client

Parameters:
hs_tftp_ev_fn_t *callback_fn – function pointer to a callback function in application (user) layer code which receives notifications related to this transfer session.

typedef long hs_tftp_ev_fn_t(long handle, int ev_code, long arg1, long arg2);
handle – application layer handle
ev_code – event, one of the following:
HS_TFTP_EV_ERR_TMOUT – session timed out and closed
HS_TFTP_RX_COMPLETE – receive transfer completed successfully
Arg1 and arg2 are currently unused

long *handle – pointer to long variable to received TFTP module connection handle after file transfer is initiated.

long user_handle – application layer context handle. This handle is saved into corresponding TFTP session context and is returned unchanged as a parameter in various notification callbacks from HS TFTP to application layer code.

Return values: 

Sample usage: 

/* server mode - process file read request */
void process_file_read_request(unsigned char *filename, long arg2)
{
          int rc;
          long fsize = 0;

          unsigned char ipstr[20] = {0};
          server_conn_ctx_t *pCtx;

          HsSockInetNtoa(arg2, ipstr);
          printf("file read request from (%s) %s\n", ipstr, filename);

          pCtx = tftp_alloc_srvconn_ctx();
          if (!pCtx)
          {
                   printf("rejected: no free contexts\n");
                   HsTftpRejectRq(HS_TFTP_EV_READ_REQ,
                          HS_TFTP_SERVER_ERR_USER, "no free contexts");
                   return;
          }         

          pCtx->hFile = FLASHOpen(filename, "r");
          if (pCtx->hFile)
                   FLASHInfo(filename, &fsize, NULL, NULL, NULL, NULL);

          if ((!pCtx->hFile) || (!fsize))
          {
                   printf("rejected: file open error\n");
                   HsTftpRejectRq(HS_TFTP_EV_READ_REQ, HS_TFTP_SERVER_ERR_FNOTFOUND, NULL);
                   hs_tftp_cleanup_ctx(pCtx);
                   return;
          } 

          pCtx->fblock = pCtx->rxbuf;
          pCtx->is_server_session = TRUE;
          pCtx->is_send = TRUE; 

          tftp_add_srvconn(pCtx);

          rc = HsTftpServerStartSend(hs_tftp_server_ev_handler, &pCtx->tftp_handle, (long)pCtx);
          if (rc != HS_TFTP_RC_OK)
          {
                   printf("Server Start Send failed RC (%u)\n", rc);
                   hs_tftp_cleanup_ctx(pCtx);
                   return;
          }

          pCtx->total_blocks = fsize / TFTP_BLK_SIZE;
          printf("Server send transfer started\n");
}

1.6      HsTftpRejectRq

Declaration:
extern void HsTftpRejectRq(int rq, int reason, unsigned char *str);

Summary:
Sends TFTP ERROR packet (in server mode) to remote TFTP client with specified reason code and descriptive ASCII string. This function may be called in response to HS_TFTP_EV_WRITE_REQ and HS_TFTP_EV_READ_REQ events.

Parameters:
rq – currently unused

reason – reason code, one of the following:
HS_TFTP_SERVER_ERR_FIO - FILE I/o error
HS_TFTP_SERVER_ERR_FNOTFOUND - file not found
HS_TFTP_SERVER_ERR_USER - user defined error, send supplied error string

Str – pointer to zero terminated ASCII string to send with the ERROR packet, only valid if reason is HS_TFTP_SERVER_ERR_USER.

Return values:
None

Sample usage: 
HsTftpRejectRq(HS_TFTP_EV_WRITE_REQ, HS_TFTP_SERVER_ERR_USER, "no free contexts");        

1.7      HsTftpTransfer

Declaration:

extern
int HsTftpTransfer(
          int                  operation,             // packet type
          unsigned long  dest_ip,                 // remote end IP address
          unsigned char *filename,               // filename (0 terminated)
          hs_tftp_ev_fn_t *callback_fn,        // event callback (used for indication of completion or error)
          unsigned short tftp_port,               // initial TFTP port of server
          long              *handle,                 // Connection handle returned after transfer initiated
          long              user_handle);           // upper layer context 

Summary:
This function is used to initiate client mode Send or Receive file transfer.

Parameters:
operation – type of transfer to start:
TFTP_OP_SEND_FILE – start sending file to remote TFTP server
TFTP_OP_GET_FILE – start receiving file from remote TFTP server

dest_ip – 32 bit remote TFTP server IP address

filename – name of file to send or receive (pointer to zero terminated ASCII string)

callback_fn – pointer to event callback used for indication of completion or errors.

Callback function prototype:
typedef long hs_tftp_ev_fn_t(long handle, int ev_code, long arg1, long arg2);
handle – user application layer context
ev_code – event, one of the following:
HS_TFTP_EV_ERR_TMOUT – TFTP transfer timed out, session closed
HS_TFTP_RX_COMPLETE – receive transfer complete
HS_TFTP_EV_ERR_RXED – remote TFTP server send aborted transfer, arg2 – pointer to zero terminated error string from received TFTP ERROR packet

tftp_port – TFTP port at remote server to send the request to (normally 69)

*handle – pointer to long variable to receive TFTP session handle after the function returns

user_handle – application layer context handle to be stored by HS TFTP module in this session context.

Return values: 

Sample usage: 

            rc = HsTftpTransfer(TFTP_OP_SEND_FILE, dest_ip, &filename[i],
                   hs_tftp_ev_handler, TFTP_PORT, &pCtx->tftp_handle, (long)pCtx);

1.8      HsTftpTimerExpired

Declaration:
extern void HsTftpTimerExpired(long tftp_handle);

Summary:
Function called from user code when timer previously started by HS TFTP has expired

Parameters:
tftp_handle - TFTP module session handle

Return values:
None

Sample usage: 

/*
 * os timer callback
 */
static void TimerProc(void *context)
{
          server_conn_ctx_t *pCtx = (server_conn_ctx_t *)context;
 
          if (!pCtx) return;         

          TIMERDelete(pCtx->Timer);

          HsTftpTimerExpired((long)pCtx->tftp_handle);

}

1.9      HsTftpAbort

Declaration:
extern int HsTftpAbort(long handle);

Summary:
Abort current operation and cleanly disconnect remote end based on passed connection handle. This function is going to send TFTP ERROR packet to remote end with the string “Aborted by user” and cleanup local TFTP session context.

Parameters:
handle – TFTP module session handle

Return values: 

Sample usage:

HsTftpAbort(pCtx->tftp_handle);

NEXT STEPS?

Ordering and Pricing | Contact Us | Sample Source | User Manual | Terms of License