Serial to Ethernet Converter

Transcription

1 Serial to Ethernet Converter SOFTWARE REFERENCE MANUAL sw01266-srm-195 Copyright 2007 Luminary Micro, Inc.

2 Legal Disclaimers and Trademark Information INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH LUMINARY MICRO PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN LUMINARY MICRO S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, LUMINARY MICRO ASSUMES NO LIABILITY WHATSOEVER, AND LUMINARY MICRO DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF LUMINARY MICRO S PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICU- LAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. LUMINARY MICRO S PRODUCTS ARE NOT INTENDED FOR USE IN MEDICAL, LIFE SAVING, OR LIFE-SUSTAINING APPLICATIONS. Luminary Micro may make changes to specifications and product descriptions at any time, without notice. Contact your local Luminary Micro sales office or your distributor to obtain the latest specifications and before placing your product order. Designers must not rely on the absence or characteristics of any features or instructions marked reserved or undefined. Luminary Micro reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. Copyright Luminary Micro, Inc. All rights reserved. Stellaris, Luminary Micro, and the Luminary Micro logo are registered trademarks of Luminary Micro, Inc. or its subsidiaries in the United States and other countries. ARM and Thumb are registered trademarks and Cortex is a trademark of ARM Limited. Other names and brands may be claimed as the property of others. Luminary Micro, Inc. 108 Wild Basin, Suite 350 Austin, TX Main: Fax: Revision Information This is version 195 of this document, last updated on. 2

3 Serial to Ethernet Converter Software Reference Manual Table of Contents Legal Disclaimers and Trademark Information Revision Information Introduction Configuration Application Introduction Definitions Company Information Support Information

4 Table of Contents 4

5 Serial to Ethernet Converter Software Reference Manual 1 Introduction This document describes the functions, variables, structures, and defines in the software for the Serial to Ethernet Converter. The converter provides a means of accessing a UART over the Ethernet using a Stellaris microcontroller as the bridge between the two interfaces. The ZIP file containing the source code for the Serial to Ethernet Converter should be extracted into the same directory to which DriverLib was extracted. For example, if DriverLib was extracted to C:\ (meaning there is a C:\DriverLib directory), then the ZIP file for the converter source should be extracted to C:\ as well. It will create a DriverLib\AppNotes\sw01266 directory that contains the source code for the application. Once extracted, the code can be built just like any other DriverLib example; either by typing "make" from the command line or by using the Keil RV-MDK or IAR EW-ARM project files. Source Code Overview The following is an overview of the files that comprise the Serial to Ethernet Converter application. EULA.txt Makefile config.h lwipopts.h ser2enet.opt ser2enet.uv2 ser2enet.c ser2enet.ewd ser2enet.ewp ser2enet.eww ser2enet_sourcerygxx.ld startup_ewarm.c startup_gcc.c The full text of the End User License Agreement that covers the use of this software package. The rules for building the Serial to Ethernet Converter application from the command line. The file that contains the configuration of the Serial to Ethernet Converter application. The file that contains the configuration for the lwip TCP/IP stack. The project files for building the Serial to Ethernet Converter application using the Keil uvision GUI. The file that contains the source code for the Serial to Ethernet Converter application. The project files for building the Serial to Ethernet Converter application using the IAR Embedded Workbench GUI. The linker script used when linking the Serial to Ethernet Converter application using CodeSourcery s SourceryG++. The startup code used when building the Serial to Ethernet Converter application using IAR s Embedded Workbench. The startup code used when building the Serial to Ethernet Converter application using GNU GCC. 5

6 Introduction startup_rvmdk.s startup_sourcerygxx.c telnet.h The startup code used when building the Serial to Ethernet Converter application using Keil s RealView Microcontroller Development Kit. The startup code used when building the Serial to Ethernet Converter application using CodeSourcery s SourceryG++ for Stellaris EABI. The file that contains the definitions of the telnet commands and options, as defined by the appropriate Internet Engineering Task Force (IETF) standards. 6

7 Serial to Ethernet Converter Software Reference Manual 2 Configuration The configuration of the Serial to Ethernet Converter application is contained in config.h. The following configurations values are available: USE_STATIC_IP If defined, specifies that a static IP configuration should be used. STATIC_IPADDR?, STATIC_NETMASK?, and STATIC_GWADDR? are used to specify the static IP configuration in this case. When using static IP configuration, nothing is done to accommodate the presence of another device on the network with the same IP address (it is therefore the user s responsibility to guarantee that this does not happen). This option can not be defined at the same time as the USE_DHCP option. STATIC_IPADDR0 STATIC_IPADDR1 STATIC_IPADDR2 STATIC_IPADDR3 The converter s IP address when using static IP configuration. STATIC_IPADDR0 is the first byte of the IP address, STATIC_IPADDR1 is the second byte, and so on. For example, to specify a static IP address of , STATIC_IPADDR0 would be 169. See for more details on the IP address. STATIC_NETMASK0 STATIC_NETMASK1 STATIC_NETMASK2 STATIC_NETMASK3 The IP netmask to use when using static IP configuration. This is specified in the same manner as the static IP address. The setting of the netmask will vary from network to network, based on the IP address class and individual choices made during the configuration of a particular network. See for more details on the IP netmask. STATIC_GWADDR0 STATIC_GWADDR1 STATIC_GWADDR2 STATIC_GWADDR3 The IP address of the default gateway when using static IP configuration. This is specified in the same manner as the static IP address. The setting of the default gateway will vary from network to network, base on the IP address class and individual choices made during the configuration of a particular network. See for more details on the default gateway. 7

8 Configuration USE_DHCP If defined, specifies that the Dynamic Host Configuration Protocol (DHCP) should be used to configure the IP address, netmask, and default gateway. When using DHCP, an automatic allocation should be made in the DHCP server so that the serial to Ethernet converter will always be assigned the same IP address. This option can not be defined at the same time as the USE_STATIC_IP option. See for more details on DHCP and automatic allocations. TELNET_PORT The TCP port number for the telnet server that is connected to the UART. There is no Internet Assigned Numbers Authority (IANA) defined port for use by a telnet connection to a serial port, though port 23 is define for use by a telnet server. Since the telnet server is the only service provided by the serial to Ethernet converter, this can really be any any possible port, though confusion could result from reusing standard ports (such as 443, which is used for HTTPS). See for more details on TCP port numbers. TELNET_TIMEOUT The timeout, in second, before an idle telnet connection is automatically closed. If set to zero, automatic closing of an idle connection is disabled. This can useful in two situations: closing connections that have become idle and detecting a broken link between the client and server. Closing an idle connection is useful if it is desireable to free the resource for use by others. Detecting a broken link is useful since it prevents the converter from continually trying to send data to the client, unnecessarily congesting the local segment of the network. If there may be long periods of inactivity on the serial port, it may not be possible to safely use the idle timer since there is no way to distinguish an idle connection from a broken link (a broken link can only be detected if there is traffic on the link). If the client is able to periodically send a telnet NOP command, the idle timer can be used to detect a broken link and handle it appropriately. UART_BAUDRATE The baud rate used in the configuration of the UART. This is specified as an integer, with being the largest possible value (3.125 Mbaud). Standard values can be used (such as 9600, , and so on), as well as non-standard value (such as 56789). The selected baud rate must match the baud rate of the connected serial device. 8

9 Serial to Ethernet Converter Software Reference Manual UART_DATABITS UART_PARITY UART_STOPBITS The number of data bits in each byte transmitted and received on the UART; either 5, 6, 7, or 8 data bits may be used. This is specified as UART_CONFIG_WLEN_5, UART_CONFIG_WLEN_6, UART_CONFIG_WLEN_7, or UART_CONFIG_WLEN_8. The selected number of data bits must match the format used by the connected serial device. The parity applied to each byte transmitted or received on the UART; even, odd, or no parity may be used. This is specified as UART_CONFIG_PAR_NONE, UART_CONFIG_PAR_EVEN, or UART_CONFIG_PAR_ODD. The selected parity must match the format used by the connected serial device. The number of stop bytes following each byte transmitted or received on the UART; one or two stop bits may be used. This is specified as UART_CONFIG_STOP_ONE or UART_CONFIG_STOP_TWO. The selected number of stop bits must match the format used by the connected serial device. 9

10 Configuration 10

11 Serial to Ethernet Converter Software Reference Manual 3 Application Introduction Definitions Introduction The Serial to Ethernet Converter provides a means of accessing the UART on a Stellaris device via a network connection. The UART can be connected to the UART on a non-networked device, providing the ability to access the device via a network. This can be useful to overcome the cable length limitations of a UART connection (in fact, the cable can become thousands of miles long) and to provide networking capability to existing devices without modifing the device s operation. The telnet protocol (as defined by RFC854) is used to make the connection across the network. The Serial to Ethernet Converter provides the telnet server, and a connection is made to the converter using a telnet client. In its simplest form, a telnet client is simply a TCP connect to the appropriate port. Telnet interprets 0xff as a command indicator (known as the Interpret As Command, or IAC, byte). Consecutive IAC bytes are used to transfer an actual 0xff byte; thus, the only special processing required is to translate 0xff to 0xff 0xff when sending, and to translate 0xff 0xff to 0xff when receiving. The WILL, WONT, DO, DONT option negotiation protocol is also imlpemented. This is a simple means of determining if capabilities are present, and for enabling or disabling features that do not require configuration. Through the use of this negotiation protocol, telnet clients and servers are able to easily match capabilities and avoid trying to configure features that are not shared by both ends of the connection (which would therefore result in the negotiation sequence being sent as actual data instead of being absorbed by the client or server). In this implementation, only the SUPPRESS_GA option is supported; all other options are negatively responded to in order to prevent the client from trying to use them. The converter can be configured to use a static IP configuration or to use DHCP to obtain its IP configuration. Since the converter is providing a telnet server, the effective use of DHCP requires a reservation in the DHCP server so that the converter gets the same IP address each time it is connected to the network. 3.2 Definitions Data Structures ttelnetopts Defines FLAG_RXPKT FLAG_RXUART 11

12 Application FLAG_SYSTICK OPT_FLAG_DO OPT_FLAG_WILL SYSTICKHZ SYSTICKMS UART_BUF_SIZE Enumerations ttelnetstate Functions void EthernetIntHandler (void) static void lwipinit (void) int main (void) void SysTickIntHandler (void) static err_t TelnetAccept (void arg, struct tcp_pcb pcb, err_t err) static void TelnetClose (struct tcp_pcb pcb) static void TelnetError (void arg, err_t err) static err_t TelnetPoll (void arg, struct tcp_pcb pcb) static void TelnetProcessCharacter (unsigned char ucchar) static void TelnetProcessDo (unsigned char ucoption) static void TelnetProcessDont (unsigned char ucoption) static void TelnetProcessWill (unsigned char ucoption) static void TelnetProcessWont (unsigned char ucoption) static err_t TelnetReceive (void arg, struct tcp_pcb pcb, struct pbuf p, err_t err) static err_t TelnetSent (void arg, struct tcp_pcb pcb, u16_t len) void UARTIntHandler (void) static void UARTSend (unsigned char ucchar) Variables static ttelnetstate g_estate static ttelnetopts g_psoptions[ ] static struct tcp_pcb g_pstelnetpcb static unsigned char g_pucrxbuffer[uart_buf_size] static unsigned char g_puctelnetbuffer[512] static const unsigned char g_puctelnetinit[ ] static unsigned char g_puctxbuffer[uart_buf_size] static struct netif g_semac_if static unsigned long g_ularptimer static unsigned long g_ulconnectiontimeout static unsigned long g_uldhcpcoarsetimer 12

13 Serial to Ethernet Converter Software Reference Manual static unsigned long g_uldhcpfinetimer static volatile unsigned long g_ulflags static unsigned long g_ulrxread static unsigned long g_ulrxwrite static unsigned long g_ultcpfasttimer static unsigned long g_ultcpslowtimer static unsigned long g_ultelnetlength static unsigned long g_ultxread static unsigned long g_ultxwrite Data Structure Documentation ttelnetopts typedef struct { unsigned char ucoption; unsigned char ucflags; } ttelnetopts Members: ucoption The option byte. ucflags The flags for this option. The bits in this byte are defined by OPT_FLAG_WILL and OPT_FLAG_DO. A structure that contains the state of the options supported by the telnet server, along with the possible flags Define Documentation FLAG_RXPKT The bit in g_ulflags that indicates that an Ethernet controller interrupt has occurred FLAG_RXUART The bit in g_ulflags that indicates that a UART receive interrupt has occurred FLAG_SYSTICK The bit in g_ulflags that indicates that a SysTick interrupt has occurred. 13

14 Application OPT_FLAG_DO The bit in the ucflags member of ttelnetopts that is set when the remote client has sent a DO request and the server has accepted it OPT_FLAG_WILL The bit in the ucflags member of ttelnetopts that is set when the remote client has sent a WILL request and the server has accepted it SYSTICKHZ The number of times per second that the SysTick timer generates a processor interrupt SYSTICKMS The number of milliseconds between SysTick generated processor interrupts UART_BUF_SIZE The size of the buffers used for transmitting to and receiving from the UART Enumeration Documentation ttelnetstate The possible states of the telnet option parser. Enumerators: STATE_NORMAL The telnet option parser is in its normal mode. Characters are passed as is until an IAC byte is received. STATE_IAC The previous character received by the telnet option parser was an IAC byte. STATE_WILL The previous character sequence received by the telnet option parser was IAC WILL. STATE_WONT The previous character sequence received by the telnet option parser was IAC WONT. STATE_DO The previous character sequence received by the telnet option parser was IAC DO. STATE_DONT The previous character sequence received by the telnet option parser was IAC DONT. 14

15 Serial to Ethernet Converter Software Reference Manual Function Documentation EthernetIntHandler Handles the Ethernet interrupt. void EthernetIntHandler(void) This function is called when the Ethernet controller generates an interrupt as a result of the reception of a packet. It sets a flag indicating that lwip should read the packet when possible. None lwipinit [static] Initializes the lwip TCP/IP stack. static void lwipinit(void) This function handles the initialization of the lwip TCP/IP stack, along with configuration of the Ethernet controller and the lwip driver for it. None main Handles the main application loop. int main(void) This function initializes and configures the device and the software, then performs the main loop. All the actual TCP/IP processing occurs within this function (since lwip is not reentrant). Never returns. 15

16 Application SysTickIntHandler Handles the SysTick interrupt. void SysTickIntHandler(void) This function is called when the SysTick timer expires. It increments the lwip timers and sets a flag indicating that the timeout functions need to be called if necessary. None TelnetAccept [static] Accepts a TCP connection for the telnet port. static err_t TelnetAccept(void *arg, struct tcp_pcb *pcb, err_t err) Parameters: arg is not used in this implementation. pcb is the pointer to the TCP control structure. err is not used in this implementation. This function is called when the lwip TCP/IP stack has an incoming connection request on the telnet port. This function will return an lwip defined error code TelnetClose [static] Closes an existing Ethernet connection. static void TelnetClose(struct tcp_pcb *pcb) Parameters: pcb is the pointer to the TCP control structure. This function is called when the the TCP connection should be closed. 16

17 Serial to Ethernet Converter Software Reference Manual None TelnetError [static] Handles lwip TCP/IP errors. static void TelnetError(void *arg, err_t err) Parameters: arg is not used in this implementation. err is the error that was detected. This function is called when the lwip TCP/IP stack has detected an error. The connection is no longer valid. None TelnetPoll [static] Handles lwip TCP/IP polling and timeout requests. static err_t TelnetPoll(void *arg, struct tcp_pcb *pcb) Parameters: arg is not used in this implementation. pcb is the pointer to the TCP control structure. This function is called when the lwip TCP/IP stack has no incoming or outgoing data. It can be used to reset an idle connection. This function will return an lwip defined error code TelnetProcessCharacter [static] Processes a character received from the telnet port. static void TelnetProcessCharacter(unsigned char ucchar) 17

18 Application Parameters: ucchar is the character in question. This function processes a character received from the telnet port, handling the interpretation of telnet commands (as indicated by the telnet interpret as command (IAC) byte). None TelnetProcessDo [static] Processes a telnet DO request. static void TelnetProcessDo(unsigned char ucoption) Parameters: ucoption is the telnet option in question. This function will handle a DO request for a telnet optoin. If it is an option that is known by the telnet server, a WILL response will be generated if the option is not already enabled. For unknown options, a WONT response will always be generated. The response (if any) is written into the telnet transmit buffer. None TelnetProcessDont [static] Processes a telnet DONT request. static void TelnetProcessDont(unsigned char ucoption) Parameters: ucoption is the telnet option in question. This funciton will handle a DONT request for a telnet option. If it is an option that is known by the telnet server, a WONT response will be generated if the option is not already disabled. For unknown options, a WONT resopnse will always be generated. The response (if any) is written into the telnet transmit buffer. None. 18

19 Serial to Ethernet Converter Software Reference Manual TelnetProcessWill [static] Processes a telnet WILL request. static void TelnetProcessWill(unsigned char ucoption) Parameters: ucoption is the telnet option in question. This function will handle a WILL request for a telnet option. If it is an option that is known by the telnet server, a DO response will be generated if the option is not already enabled. For unknown options, a DONT response will always be generated. The response (if any) is written into the telnet transmit buffer. None TelnetProcessWont [static] Processes a telnet WONT request. static void TelnetProcessWont(unsigned char ucoption) Parameters: ucoption is the telnet option in question. This function will handle a WONT request for a telnet option. If it is an option that is known by the telnet server, a DONT response will be generated if the option is not already disabled. For unknown options, a DONT response will always be generated. The response (if any) is written into the telnet transmit buffer. None TelnetReceive [static] Receives a TCP packet from lwip for the telnet server. static err_t TelnetReceive(void *arg, struct tcp_pcb *pcb, struct pbuf *p, err_t err) 19

20 Application Parameters: arg is not used in this implementation. pcb is the pointer to the TCP control structure. p is the pointer to the PBUF structure containing the packet data. err is used to indicate if any errors are associated with the incoming packet. This function is called when the lwip TCP/IP stack has an incoming packet to be processed. This function will return an lwip defined error code TelnetSent [static] Handles acknowledgment of data transmitted via Ethernet. static err_t TelnetSent(void *arg, struct tcp_pcb *pcb, u16_t len) Parameters: arg is not used in this implementation. pcb is the pointer to the TCP control structure. len is the length of the data transmitted. This function is called when the lwip TCP/IP stack has received an acknowledgment for data that has been transmitted. This function will return an lwip defined error code UARTIntHandler Handles the UART interrupt. void UARTIntHandler(void) This function is called when the UART generates an interrupt. An interrupt will be generated when data is received and when the transmit FIFO becomes half empty. The transmit and receive FIFOs are processed as appropriate. None. 20

21 Serial to Ethernet Converter Software Reference Manual UARTSend [static] Sends a character to the UART. static void UARTSend(unsigned char ucchar) Parameters: ucchar is the character to be sent. This function sends a character to the UART. The character will either be directly written into the UART FIFO or into the UART transmit buffer, as appropriate. None Variable Documentation g_estate [static] static ttelnetstate g_estate The current state of the telnet option parser g_psoptions [static] static ttelnetopts g_psoptions[ ] The telnet options supported by this server g_pstelnetpcb [static] static struct tcp_pcb *g_pstelnetpcb A pointer to the telnet session PCB data structure. 21

22 Application g_pucrxbuffer [static] static unsigned char g_pucrxbuffer[uart_buf_size] The buffer used to hold characters received from the UART g_puctelnetbuffer [static] static unsigned char g_puctelnetbuffer[512] A buffer used to construct a packet of data to be transmitted to the telnet client g_puctelnetinit [static] static const unsigned char g_puctelnetinit[ ] The initialization sequence sent to a remote telnet client when it first connects to the telnet server g_puctxbuffer [static] static unsigned char g_puctxbuffer[uart_buf_size] The buffer used to hold characters to be sent to the UART g_semac_if [static] static struct netif g_semac_if The lwip network interface structure for the Stellaris Ethernet controller g_ularptimer [static] static unsigned long g_ularptimer 22

23 Serial to Ethernet Converter Software Reference Manual The lwip ARP timer, used to determine the rate at which to call etharp_tmr() g_ulconnectiontimeout [static] static unsigned long g_ulconnectiontimeout A counter for the TCP connection timeout g_uldhcpcoarsetimer [static] static unsigned long g_uldhcpcoarsetimer The lwip DHCP coarse timer, used to determine the rate at which to call dhcp_coarse_tmr() g_uldhcpfinetimer [static] static unsigned long g_uldhcpfinetimer The lwip DHCP fine timer, used to determine the rate at which to call dhcp_fine_tmr() g_ulflags [static] static volatile unsigned long g_ulflags A set of flags that indicate the occurrence of interrupts. The bits in this word are defined by FLAG_SYSTICK, FLAG_RXPKT, and FLAG_RXUART g_ulrxread [static] static unsigned long g_ulrxread The offset into the UART receive buffer (g_pucrxbuffer) where the next character is to be read. The buffer is empty when this is equal to the write offset (g_ulrxwrite), and is full when the write offset is one character behind the read offset (modulo the buffer size). 23

24 Application g_ulrxwrite [static] static unsigned long g_ulrxwrite The offset into the UART receive buffer (g_pucrxbuffer) where the next character is to be written. The buffer is empty when this is equal to the read offset (g_ulrxread), and is full when the write offset is one character behind the read offset (modulo the buffer size) g_ultcpfasttimer [static] static unsigned long g_ultcpfasttimer The lwip TCP fast timer, used to determine the rate at which to call tcp_fasttmr() g_ultcpslowtimer [static] static unsigned long g_ultcpslowtimer The lwip TCP slow timer, used to determine the rate at which to call tcp_slowtimer() g_ultelnetlength [static] static unsigned long g_ultelnetlength The number of bytes of valid data in the telnet packet buffer (g_puctelnetbuffer) g_ultxread [static] static unsigned long g_ultxread The offset into the UART transmit buffer (g_puctxbuffer) where the next character is to be read. The buffer is empty when this is equal to the write offset (g_ultxwrite), and is full when the write offset is one character behind the read offset (modulo the buffer size). 24

25 Serial to Ethernet Converter Software Reference Manual g_ultxwrite [static] static unsigned long g_ultxwrite The offset into the UART transmit buffer (g_puctxbuffer) where the next character is to be written. The buffer is empty when this is equal to the read offset (g_ultxread), and is full when the write offset is one character behind the read offset (modulo the buffer size). 25

26 Company Information Founded in 2004, Luminary Micro, Inc. designs, markets, and sells ARM Cortex-M3-based microcontrollers (MCUs). Austin, Texas-based Luminary Micro is the lead partner for the Cortex-M3 processor, delivering the world s first silicon implementation of the Cortex-M3 processor. Luminary Micro s introduction of the Stellaris family of products provides 32-bit performance for the same price as current 8- and 16-bit microcontroller designs. With entry-level pricing at $1.00 for an ARM technology-based MCU, Luminary Micro s Stellaris product line allows for standardization that eliminates future architectural upgrades or software tool changes. Luminary Micro, Inc. 108 Wild Basin, Suite 350 Austin, TX Main: Fax: sales@luminarymicro.com Support Information For support on Luminary Micro products, contact: support@luminarymicro.com , ext 3 26