 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The NetX™ Trivial File Transfer Protocol (TFTP) is a lightweight protocol designed for file transfers. Unlike more robust protocols, TFTP does not perform extensive error-checking and can have limited performance due to its stop‑and-wait protocol. After a TFTP data packet is sent, the sender waits for an ACK to be returned by the recipient. Although this process is simple, it does limit the overall TFTP throughput. The TFTP package enables hosts to use the TFTP protocol over IP networks.
The NetX TFTP Server module defines APIs for creating, deleting, generating response packets, response sending and getting information from a received packet. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.
NetX and NetX Duo TFTP Server Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| nx_tftp_server_create | nx_tftp_server_create(&my_server, "My TFTP Server", server_ip, &ram_disk, stack_ptr, 2048, pool_ptr);Create TFTP server (IPv4 only) |
| nxd_tftp_server_create** | nxd_tftp_server_create(&my_server, "My TFTP Server", &server_ip, &ram_disk, stack_ptr, 2048, pool_ptr);Create TFTP server (IPv4 and IPv6 supported). |
| nx_tftp_server_delete | nx_tftp_server_delete(&my_server);Delete TFTP server. |
| nxd_tftp_server_delete** | nxd_tftp_server_delete(&my_server);Delete TFTP server. |
| nx_tftp_server_start | nx_tftp_server_start(&my_server);Start the TFTP server. |
| nxd_tftp_server_start** | nxd_tftp_server_start(&my_server);Start the TFTP server. |
| nx_tftp_server_stop | nx_tftp_server_stop(&my_server);Stop the TFTP server. |
| nxd_tftp_server_stop** | nxd_tftp_server_stop(&my_server);Stop the TFTP server. |
**This API is only available in NetX Duo TFTP Server. For definitions of of NetX Duo specific data types, see the NetX Duo User Guide for the Renesas Synergy™ Platform.
Status Return Values
| Name | Description |
|---|---|
| NX_SUCCESS | API Call Successful |
| NX_TFTP_POOL_ERROR* | Packet pool payload is too small for the 512 bytes of TFTP data. |
| NX_PTR_ERROR* | Invalid pointer input |
| NX_CALLER_ERROR* | Invalid caller of this service |
*These error codes are only returned if error checking is enabled. Please refer to the NetX Duo User Guide for the Renesas Synergy™ Platform for more details on error checking services in NetX Duo.
To function properly, the TFTP Clients portion of the NetX Duo TFTP package requires an already-created IP instance.
The UDP must be enabled on that same IP instance. The client portion of the NetX Duo TFTP package has no further requirements.
The TFTP Server portion of the NetX TFTP package requires complete access to the UDP port 69 for handling all client TFTP requests; the TFTP Server is also designed for use with the FileX® embedded file system. If FileX is not available, the user may port portions of the FileX used to their own environment (details in later module guide sections).
File names should be in the format of the target file system. Filenames should be NULL terminated ASCII strings, with full path information, if necessary. There is no specified limit in the size of TFTP file names in the NetX Server TFTP implementation.
TFTP Messages
The TFTP has a simple mechanism for opening, reading, writing and closing files, with 2-4 bytes of the TFTP header underneath the UDP header. The definition of the TFTP file open messages has the following format:
| A | B | C | D | Fstart | Fend | 0 | | O | C | T | E | T | 0 | |--—|--—|--—|--—|-----—|---—|--—|--—|--—|--—|--—|--—|--—|--—|
Where,
File Open protocol field
| A | B | C | D | 2 Byte Opcode field |
|---|---|---|---|---|
| 0 | 0 | 0 | 1 | Open for read |
| 0 | 0 | 0 | 2 | Open for write |
Fstart - Fend, File name
0, 1-byte NULL termination character.
OCTET, ASCII "OCTET" to specify binary transfer
The definition of the TFTP write, ACK and error messages are slightly different:
| A | B | C | D | W | X | Y | Z | Nstart | Nend | |--—|--—|--—|--—|--—|--—|--—|--—|-----—|---—|
Where,
Protocol field for TFTP write
| A | B | C | D | 2 Byte Opcode field |
|---|---|---|---|---|
| 0 | 0 | 0 | 3 | Data packet |
| 0 | 0 | 0 | 4 | ACK for last read |
| 0 | 0 | 0 | 5 | Error condition |
Nstart - Nend,, n-byte Data field
WXYZ, 2-byte Block Number field (1-n)
TFTP Communication
The data packet payload containing the file to upload or download is sent in 512 byte chunks until the last packet contains less than 512 bytes, where the packet containing fewer than 512 bytes signals the end of file. The general sequence of events is as follows:
TFTP Read File Requests:
TFTP Write Requests:
The NetX TFTP Server module requires FileX media (Block media or USB Mass Storage). When a TFTP Server stack element is added to the project, an Add FileX box is attached to it. The configurator automatically sets up and initializes the FileX media for the server before the server is started. For details on configuring FileX, see the FileX™ User's Guide for the Renesas Synergy™ Platform.
The NetX TFTP Server also requires a packet pool for transmitting packets; it can share the IP default packet pool or create a separate packet pool. (Details on setting the TFTP Server packet pool are found in Including the NetX and NetX Duo TFTP Server Module in an Application.)
This section describes how to include either or both the NetX and NetX Duo TFTP Server module in an application using the SSP configurator.
To add the NetX/NetX Duo TFTP Server module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
NetX and NetX Duo TFTP Server Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_tftp0 NetX TFTPServer | Threads | New Stack> X-Ware> NetX> Protocols> NetX TFTPServer |
| g_tftp0 NetX Duo TFTPServer | Threads | New Stack> X-Ware> NetX Duo> Protocols> NetX Duo TFTP Server |
When the NetX and/or NetX Duo TFTP Server module is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.
In the stack above, the NetX Network Driver (or NetX Duo Network Driver in a NetX Duo stack) has not been populated yet. There are multiple possible selections for the Network Driver; they are not all provided so as not to needlessly complicate the figure and the following configuration tables. The available options depend on the MCU target, but some typical options include:
Additionally, in the stack above, the FileX stack has also not been populated yet. There are multiple possible selections for the FileX module; they are not all provided so as not to needlessly complicate the figure and the following configuration tables. The available options depend on the MCU target, but some typical options include:
The NetX and NetX Duo TFTP Server module must be configured by the user for the desired operation. The SSP configuration window automatically identifies (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules for successful operation. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.
Configuration Settings for the NetX and NetX Duo TFTP Server Module
| ISDE Property | Value | Description |
|---|---|---|
| FileX Support | Enable, Disable Default: Enable | FileX support selection |
| Retransmission on client request support | Enable, Disable Default: Disable | Retransmission on client request support selection |
| Internal thread priority | 16 | Internal thread priority selection |
| Maximum clients to serve simultaneously | 10 | Maximum clients to serve simultaneously selection |
| Time slice for internal thread | 2 | Time slice for internal thread selection |
| Client request activity timeout check interval (ticks) | 20 | Client request activity timeout (ticks) selection |
| Ack or data retransmission interval (ticks) | 200 | Ack or data retransmission interval (ticks) selection |
| Maximum retries for transmission without response | 5 | Maximum retries for transmission without response selection |
| Maximum retries for transmission with duplicate response | 2 | Maximum retries for transmission with duplicate response selection |
| Name | g_tftp_server0 | Module name |
| Internal thread stack size (bytes) | 2048 | Internal thread stack size (bytes) selection |
| Name of generated initialization function | tftp_server_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
In some cases, settings other than the defaults for lower-level modules can be desirable. For example, it might be useful to select different MAC Addresses. The configurable properties for the lower-level stack modules are provided in the following sections for completeness and as a reference.
Note: Most of the property settings for lower-level modules are intuitive and usually can be determined by inspection of the associated properties window from the SSP configurator.
Only a small number of settings must be modified from the default for the IP layer and lower-level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and are locked to prevent user modification. The following table identifies all the settings within the properties section for the module:
Configuration Settings for the NetX and NetX Duo IP Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_ip0 | Module name |
| IPv4 Address (use commas for separation) | 192,168,0,2 | IPv4 Address selection |
| Subnet Mask (use commas for separation) | 255,255,255,0 | Subnet Mask selection |
| Default Gateway Address (use commas for separation) | 0,0,0,0 | Default gateway address selection |
| **IPv6 Global Address (use commas for separation) | 0x2001, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x1 | IPv6 global address selection |
| **IPv6 Link Local Address (use commas for separation, All zeros means use MAC address) | 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0 | IPv6 link local address selection |
| IP Helper Thread Stack Size (bytes) | 2048 | IP Helper Thread Stack Size (bytes) selection |
| IP Helper Thread Priority | 3 | IP Helper Thread Priority selection |
| ARP | Enable | ARP selection |
| ARP Cache Size in Bytes | 512 | ARP Cache Size in Bytes selection |
| Reverse ARP | Enable, Disable Default: Disable | Reverse ARP selection |
| TCP | Enable, Disable Default: Enable | TCP selection |
| UDP | Enable, Disable Default: Enable | UDP selection |
| ICMP | Enable, Disable Default: Enable | ICMP selection |
| IGMP | Enable, Disable Default: Enable | IGMP selection |
| IP fragmentation | Enable, Disable Default: Disable | IP fragmentation selection |
| Name of generated initialization function | ip_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization function |
| Link status change callback | NULL | Link status change callback selection |
** Indicates properties that are only available in NetX Duo.
Configuration Settings for the NetX and NetX Duo TFTP Common Instance
| ISDE Property | Value | Description |
|---|---|---|
| Maximum error string length (bytes) | 64 | Maximum error string length selection |
| Time to live | 128 | Time to live selection |
| Type of Service for UDP requests | Normal, Minimum delay, Maximum data, Maximum reliabililty, Minimum cost Default: Normal | Type of service UDP requests selection |
| Fragmentation option | Don't fragment, Fragment okay Default: Don't fragment | Fragment option selection |
Configuration Settings for the NetX and NetX Duo Common Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name of generated initialization function | nx_common_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
Configuration Settings for the NetX and NetX Duo Packet Pool Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_packet_pool0 | Module name |
| Packet Size in Bytes | 640 | Packet size selection |
| Number of Packets in Pool | 16 | Number of packets in pool selection |
| Name of generated initialization function | packet_pool_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
The ETHERC peripheral module uses the PCLKA as its clock source. The PCLKA frequency is set using the SSP configurator Clock tab prior to a build or by using the CGC interface at run-time.
The ETHERC peripheral module uses pins on the MCU device to communicate to external devices. I/O pins must be selected and configured by the external device as required. The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example selection for the I2C pins.
Pin Selection for the ETHERC Module
| Resource | ISDE Tab | Pin Selection Sequence |
|---|---|---|
| ETHERC | Pins | Select Peripherals > Connectivity:ETHERC > ETHERC1.RMII |
Pin Configuration Settings for the ETHERC1
| Property | Value | Description |
|---|---|---|
| Operation Mode | Disabled, Custom, RMII Default: Disabled | Select RMII as the Operation Mode for ETHERC1 |
| Pin Group Selection | Mixed, _A only Default: _A only | Pin group selection |
| REF50CK | P701 | REF50CK Pin |
| TXD0 | P700 | TXD0 Pin |
| TXD1 | P406 | TXD1 Pin |
| TXD_EN | P405 | TXD_EN Pin |
| RXD0 | P702 | RXD0 Pin |
| RXD1 | P703 | RXD1 Pin |
| RX_ER | P704 | RX_ER Pin |
| CRS_DV | P705 | CRS_DV Pin |
| MDC | P403 | MDC Pin |
| MDIO | P404 | MDIO Pin |
The steps in using the NetX and NetX Duo TFTP Server module in a typical application are:
1. Create the TFTP server using the nx_tftp_server_create API.
2. Prepare the FileX on Block media or USB mass storage API.
3. Start the TFTP Server using the nx_tftp_server_start API.
4. The TFTP Server now periodically checks for inactivity on active client connections.
5. All received packets are checked for being duplicate packets the server already received.
6. Receive a client open for read request (internal operation).
7. Check if the server can accommodate another client request (set by Maximum clients to server simultaneously property) (internal operation).
8. Download packets of file data in 512 chunks till the last packet (internal operation).
9. Close a file and delete the client request (internal operation).
The following figure illustrates common steps in a typical operational flow diagram:
