weAut_01 / weAutSys    R 2.2.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Files
Configuration options for uIP
+ + uIP -- Adam Dunkels' TCP/IP stack + +

Overview

uIP is configured using the per-project configuration file uipopt.h. This file contains all compile-time options for uIP and should be tweaked to match each specific project. The uIP distribution contains a documented example "uipopt.h" that can be copied and modified for each project.

Note:
Most of the configuration options in the uipopt.h should not be changed, but rather the per-project uip-conf.h file.

Files

file  uip-conf.h
 

IP configuration file.


file  uipopt.h
 

Configuration options for uIP.


Project-specific configuration options

uIP has a number of configuration options that can be overridden for each project.

These are kept in a project-specific uip-conf.h file and all configuration names have the prefix UIP_CONF.

typedef uint8_t uip_tcp_appstate_t [SIZE_OF_BIGGEST_APPSTATE]
 The type of appstate in uip_conn.
void uip_appcall (void)
 The uIP event function.
void udp_appcall (void)
 The uIP udp event function.
#define UIP_CONF_UDP_CONNS   10
 Maximum number of UDP connections.
#define UIP_CONF_MAX_CONNECTIONS   10
 Maximum number of TCP connections.
#define UIP_CONF_MAX_LISTENPORTS
 Maximum number of listening TCP ports.
#define UIP_CONF_ARPTAB_SIZE   12
 The size of the ARP table.
#define UIP_CONF_BUFFER_SIZE   620
 uIP buffer size
#define UIP_CONF_BYTE_ORDER   UIP_LITTLE_ENDIAN
 CPU byte order.
#define UIP_CONF_LOGGING
 Logging on or off.
#define UIP_CONF_UDP
 UDP support on or off.
#define UIP_CONF_UDP_CHECKSUMS   1
 UDP checksums on or off.
#define UIP_CONF_INC_CHECKSUMS   0
 Check incoming checksums on or off.
#define UIP_CONF_STATISTICS   0
 uIP statistics on or off
#define UIP_CONF_BROADCAST
#define UIP_APPCALL
 Macro to name the uIP event function.
#define UIP_UDP_APPCALL
 Macro to name the uIP udp event function.

Static configuration options

These configuration options can be used for setting the IP address settings statically, but only if UIP_FIXEDADDR is set to 1.

The configuration options for a specific node includes IP address, netmask and default router as well as the Ethernet address. The netmask, default router and Ethernet address are applicable only if uIP should be run over Ethernet.

All of these should be changed to suit your project.

#define UIP_FIXEDADDR
 Determines if uIP should use a fixed IP address or not.
#define UIP_PINGADDRCONF
 Ping IP address assignment.

IP configuration options

#define UIP_TTL
 The IP TTL (time to live) of IP packets sent by uIP.
#define UIP_REASSEMBLY
 Turn on support for IP packet re-assembly.
#define UIP_REASS_MAXAGE
 maximum wait time an IP fragment in the re-assembly buffer

UDP configuration options

#define UIP_UDP
 UDP support should be compiled in (or not)
#define UIP_UDP_CHECKSUMS
 Checksums should be used (or not)
#define UIP_INC_CHECKSUMS   0
 Check incoming checksums on or off.
#define UIP_UDP_CONNS
 Maximum amount of concurrent UDP connections.

TCP configuration options

#define UIP_ACTIVE_OPEN
 Support for opening connections from uIP should be compiled in (ot not)
#define UIP_CONNS
 The maximum number of simultaneously open TCP connections.
#define UIP_LISTENPORTS
 The maximum number of simultaneously listening TCP ports.
#define UIP_URGDATA
 Support for TCP urgent data notification should be compiled in (or not)
#define UIP_RTO
 The initial retransmission timeout counted in timer pulses.
#define UIP_MAXRTX
 The maximum number of times a segment should be retransmitted.
#define UIP_MAXSYNRTX
 The maximum number of times a SYN segment should be retransmitted.
#define UIP_TCP_MSS
 The TCP maximum segment size.
#define UIP_RECEIVE_WINDOW
 The size of the advertised receiver's window.
#define UIP_TIME_WAIT_TIMEOUT
 How long a connection should stay in the TIME_WAIT state.

ARP configuration options

#define UIP_ARPTAB_SIZE
 The size of the ARP table.
#define UIP_ARP_MAXAGE
 The maximum age of ARP table entries measured in 10 seconds unit.

General configuration options

void uip_log (char *msg)
 Print out a uIP log message.
#define UIP_BUFSIZE
 The size of the uIP packet buffer.
#define UIP_STATISTICS
 Statistics support should be compiled in (or not)
#define UIP_LOGGING
 Logging of certain events should be compiled in (or not)
#define UIP_BROADCAST
 Broadcast support.
#define UIP_LLH_LEN
 The link level header length.

CPU architecture configuration

The CPU architecture configuration is where the endianess of the CPU on which uIP is to be run is specified.

Most CPUs today are little endian, including Intel (x86) and ATmega. The most notable exception are Motorola's CPUs which are big endian. The BYTE_ORDER macro must reflect the CPU architecture on which uIP is to be run.

#define UIP_BYTE_ORDER
 The byte order of the CPU on which uIP is to be run.
#define UIP_ARCH_ADD32
 There is a platform implementation of 32bit big endian addition.

Application specific configurations

An uIP application is implemented using a single application function that is called by uIP whenever a TCP/IP event occurs.

The name of this function must be registered with uIP at compile time using the UIP_APPCALL definition.

uIP applications can store the application state within the uip_conn structure by specifying the type of the application structure by typedef'ing the type uip_tcp_appstate_t and uip_udp_appstate_t.

The file containing the definitions must be included in the uipopt.h file.

The following example illustrates how this can look.

void httpd_appcall(void);
#define UIP_APPCALL     httpd_appcall

struct httpd_state {
  uint8_t state;
  uint16_t count;
  char *dataptr;
  char *script;
};
typedef struct httpd_state uip_tcp_appstate_t
typedef uint16_t uip_udp_appstate_t
 The type of appstate in an uip_udp_conn.

Define Documentation

#define UIP_CONF_UDP_CONNS   10

Maximum number of UDP connections.

This value determines the length of the UDP connections list (array uip_udp_conns). As the uip_udp_conn structure is quite small (~ 11 byte) this value is not critical.

  See also:   UIP_UDP_CONNS

#define UIP_CONF_MAX_CONNECTIONS   10

Maximum number of TCP connections.

This value determines the length of the TCP connections list (array uip_conns). As the uip_conn structure is very large (> kByte if http is used) this value is critical.

  See also:   UIP_CONNS

Maximum number of listening TCP ports.

  See also:   UIP_LISTENPORTS

#define UIP_CONF_ARPTAB_SIZE   12

The size of the ARP table.

This option should be set to a larger value if this uIP node will have many connections from the local network. (uIP default would be 8)

#define UIP_CONF_BUFFER_SIZE   620

uIP buffer size

This is the size of uIP's global transfer (RAM) buffer uIP uses for sending and receiving, also for prepended ARP.
A.D. used 420 byte. A value > 590 allows to work with some DHCP servers (like Fritz!boxes) without restrictions.

#define UIP_CONF_BYTE_ORDER   UIP_LITTLE_ENDIAN

CPU byte order.

ATmega and AVR GCC used in weAutSys are little endian.

With this setting for uIP we are on the save side. uIP does have this macro to be architecture independent, but there is uIP code just assuming little endian.

Logging on or off.

Used to set UIP_LOGGING

#define UIP_CONF_UDP

UDP support on or off.

Used to set UIP_UDP

#define UIP_CONF_UDP_CHECKSUMS   1

UDP checksums on or off.

Used to set UIP_UDP_CHECKSUMS

#define UIP_CONF_INC_CHECKSUMS   0

Check incoming checksums on or off.

Consideration and experiment show this can safely be turned off. (ENC checks incoming aggregate checksum and drops spoiled packets.

Used to set UIP_INC_CHECKSUMS

#define UIP_CONF_STATISTICS   0

uIP statistics on or off

Used to set UIP_STATISTICS

#define UIP_APPCALL

Macro to name the uIP event function.

An uIP application is implemented using a single application function that is called by uIP whenever a TCP/IP event occurs. The name of this function must be registered with uIP at compile time using this UIP_APPCALL definition.

The function named must return void and take no arguments. It will be called on uIP events.

The applications provided by uIP (like Telnet etc.) will set this macro to their specific event function, if not yet set. If there are multiple applications the function set here must handle them all, e.g. by acting as forwarder to the application specific functions.

uIP applications can store the application state within the uip_conn structure by specifying the type of the application structure by typedef'ing the type uip_tcp_appstate_t and uip_udp_appstate_t.

Remark by A.W.: A.D.'s typedef'ing approach (recommended here some ten years ago) does not carry further than to single TCP/IP application. But using more than one application and hence contradictory definitions (distributed all over original uIP's sources) causes trouble. Obviously (by now) a union of all state structures by all applications used is what A.D. must have meant in the end and what is done by weAutSys.

  See also:   uip_appcall

#define UIP_UDP_APPCALL

Macro to name the uIP udp event function.

See also:
handle_dhcp()
udp_appcall
UIP_APPCALL
#define UIP_FIXEDADDR

Determines if uIP should use a fixed IP address or not.

If uIP should use a fixed IP address, the settings are set in the uipopt.h file. If not, the macros uip_sethostaddr(), uip_setdraddr() and uip_setnetmask() should be used instead.

Ping IP address assignment.

uIP uses a "ping" packets for setting its own IP address if this option is set. If so, uIP will start with an empty IP address and the destination IP address of the first incoming "ping" (ICMP echo) packet will be used for setting the hosts IP address.

Note:
This works only if UIP_FIXEDADDR is 0.
#define UIP_TTL

The IP TTL (time to live) of IP packets sent by uIP.

This should normally not be changed.

#define UIP_REASSEMBLY

Turn on support for IP packet re-assembly.

uIP supports re-assembly of fragmented IP packets. This feature requires an additional amount of RAM to hold the re-assembly buffer and the re-assembly code size is approximately 700 bytes. The reassembly buffer is of the same size as the uip_buf buffer (configured by UIP_BUFSIZE).

Note:
IP packet re-assembly is not heavily tested.

maximum wait time an IP fragment in the re-assembly buffer

If the specified time expires, the fragment will be dropped.

Checksums should be used (or not)

Note:
Support for UDP checksums is currently not included in uIP, so this option has no function [AD] (which is not quite true [AW]).
#define UIP_INC_CHECKSUMS   0

Check incoming checksums on or off.

Consideration and experiment show this can safely be turned off. (ENC checks incoming aggregate checksum and drops spoiled packets.

Used to set UIP_INC_CHECKSUMS

#define UIP_ACTIVE_OPEN

Support for opening connections from uIP should be compiled in (ot not)

If the applications that are running on top of uIP for this project do not need to open outgoing TCP connections, this configuration option can be turned off to reduce the code size of uIP.

#define UIP_CONNS

The maximum number of simultaneously open TCP connections.

Since the TCP connections are statically allocated, turning this configuration knob down results in less RAM used. Each TCP connection requires approximately 30 bytes of memory.

#define UIP_LISTENPORTS

The maximum number of simultaneously listening TCP ports.

Each listening TCP port requires 2 bytes of memory.

#define UIP_URGDATA

Support for TCP urgent data notification should be compiled in (or not)

Urgent data (out-of-band data) is a rarely used TCP feature that would be required quite seldom.

#define UIP_RTO

The initial retransmission timeout counted in timer pulses.

This should not be changed.

#define UIP_MAXRTX

The maximum number of times a segment should be retransmitted.

Thereafter the connection should be aborted.
This should not be changed.

#define UIP_MAXSYNRTX

The maximum number of times a SYN segment should be retransmitted.

Thereafter the a connection request should be deemed to have been unsuccessful.
This should not need to be changed.

#define UIP_TCP_MSS

The TCP maximum segment size.

This is should not be to set to more than UIP_BUFSIZE - UIP_LLH_LEN - UIP_TCPIP_HLEN.

The size of the advertised receiver's window.

Should be set low (i.e., to the size of the uip_buf buffer) is the application is slow to process incoming data, or high (32768 bytes) if the application processes data quickly.

How long a connection should stay in the TIME_WAIT state.

This configuration option has no real implication, and it should be left untouched.

#define UIP_ARPTAB_SIZE

The size of the ARP table.

This option should be set to a larger value if this uIP node will have many connections from the local network.

#define UIP_ARP_MAXAGE

The maximum age of ARP table entries measured in 10 seconds unit.

A value 120 corresponds to 20 minutes life time of an ARP entry (the BSD default). As the ARP tick and the ARP entry stamps are unsigned 8 bit the value must be < 255.

In a stable (automation private) network environment invalidating ARP entries might be a nuisance as uIP might throw prepared send packets away if the ARP look-up fails — a burden to higher level protocols and the µController. It might be indicated to either raise this value or call uip_arp_timer less often in the runtime (weAutSys).

#define UIP_BUFSIZE

The size of the uIP packet buffer.

The uIP packet buffer should not be smaller than 60 bytes, and does not need to be larger than 1500 bytes. The lower the size the lower will be the TCP throughput.

  See also:   UIP_CONF_BUFFER_SIZE

#define UIP_STATISTICS

Statistics support should be compiled in (or not)

The statistics is useful for debugging and to show the user.

  See also:   UIP_CONF_STATISTICS

#define UIP_LOGGING

Logging of certain events should be compiled in (or not)

This is useful mostly for debugging. The function uip_log() must be implemented to suit the architecture of the project, if logging is turned on.

#define UIP_BROADCAST

Broadcast support.

This flag configures IP broadcast support. This is useful only together with UDP.

#define UIP_LLH_LEN

The link level header length.

This is the offset into the uip_buf where the IP header can be found. For Ethernet, this should be set to 14. For SLIP, this should be set to 0.

#define UIP_BYTE_ORDER

The byte order of the CPU on which uIP is to be run.

This option can be either BIG_ENDIAN (Motorola, SUN and some SIMATIC) or LITTLE_ENDIAN (Intel, ATmega and almost all else).

#define UIP_ARCH_ADD32

There is a platform implementation of 32bit big endian addition.

  See also:   add16littleTo32bigEndian


Typedef Documentation

The type of appstate in uip_conn.

uip_con.appstate will have to be cast to application specific types, usually struct struct thr_data_t.

typedef uint16_t uip_udp_appstate_t

The type of appstate in an uip_udp_conn.

The type of the application state that is to be stored in the uip_conn structure. This usually is typedef:ed to a struct holding application state information.


Function Documentation

void uip_appcall ( void  )

The uIP event function.

The reason for being called will be in uip_flags.

  See also:   UIP_APPCALL

void udp_appcall ( void  )

The uIP udp event function.

The reason for being called will be in the uip_udp_conn structure, especially in the ports.

  See also:   UIP_UDP_APPCALL

void uip_log ( char *  msg)

Print out a uIP log message.

This function must be implemented by the module that uses uIP, and is called by uIP whenever a log message is generated.