Programmer's Reference

Jump to: navigation, search

Table of Contents


ARP/Routing Table API

BSD 4.4 Socket API

Call Back Function Registration

Compiler Library Replacement Functions


Device/Interface API


Ethernet Link Layer API


IEEE 802.3 Ethernet Link Layer API


IGMP Filtering API

This is an extension to the IPv4 layer to include IGMP filtering functionality. Each context provides a single user-defined IGMP filter callback function which provides the IGMP header information of a packet. Further processing within this callback can modify the way the stack treats the packet.

All interface user IGMP filter callbacks (for a given context) are delivered to the same function. However, IGMP filtering can be dynamically enabled/disabled for each interface to streamline processing logic.

To implement IGMP User Filtering, do the following:

  1. Create one or more contexts
  2. Register the user IGMP filter callback for each context
  3. When creating interfaces, modify interface options to enable/disable IGMP filtering

To enable IGMP Filtering, TM_USE_IGMP_FILTERING must be defined. This will allow IP Fragments to be delivered to a user-specified IGMP callback function on a per-interface basis. These callbacks can be enabled/disabled for each device however TM_USE_IGMP_FILTERING must be enabled before any IGMP filter callback processing logic executes.

IP-Forwarding Statistics API


IPv4 Filtering API

This is an extension to the IPv4 layer to include filtering functionality. Each context provides a single user-defined IP filter callback function which provides the IP and ULP header information of a packet along with the raw data in the IP datagram. Further processing within this callback can modify the way the stack treats the packet.

All interface user IP filter callbacks (for a given context) are delivered to the same function. However, IP filtering can be dynamically enabled/disabled for each interface to streamline processing logic.

To implement IP User Filtering, do the following:

  1. Create one or more contexts
  2. Register the user IP filter callback for each context
  3. When creating interfaces, modify interface options to enable/disable filtering

To enable IPv4 Filtering, TM_USE_FILTERING must be defined. This will allow IP Fragments to be delivered to a user-specified IP callback function on a per-interface basis. These callbacks can be enabled/disabled for each device however TM_USE_FILTERING must be enabled before any IP filter callback processing logic executes.

IPv6 Filtering API

This is an extension to the IPv6 layer to include Filtering functionality. Each Context provides a single IPv6 User Filter Callback function which provides the IPv6 header information of a packet along with the raw data in the IPv6 Datagram (which can be made contigurous). Further processing within this callback can modify the way the stack treats the packet.

All interface IPv6 User Filter Callbacks (for a given context) are delivered to the same function. However, Filtering can be dynamically enabled/disabled for each interface to streamline processing logic.

To implement User Filtering, do the following:

  • Create one or more Contexts
  • Register the IPv6 User Filter Callback for each Context
  • When creating Interfaces, modify interface options to enable/disable IPv6 Filtering

The following describes the interface support and implementation for this functionality.

Compile Time Settings

Define TM_6_USE_FILTERING in <trsystem.h> to allow IPv6 Fragments to be delivered to a user-specified callback function on a per-interface basis. These IPv6 callbacks can be enabled/disabled for each device however this macro must be enabled before any IPv6 filter callback processing logic is processed.

Define TM_6_USE_FILTERING_CONT_DATA macro to make the IPv6 header in the registered IPv6 filter call back function contiguous. This allows the user to peek at the data, but will cause an extra copy of the data if the data is scattered.

Run Time Settings

At run time the user must enable filtering on the desired interface via tfInterfaceSetOptions() and the TM_6_DEV_OPTIONS_FILTER option. The user must also register a filter callback function with Treck via tf6UserRegisterFilter().

Dynamically Control the TCP Retransmission Timer

Treck allows dynamically changing the behavior of the TCP Retransmission timer on a socket-by-socket basis. More specifically, this allows the TCP Retransmission Timer to be Paused, Resumed, or Reset. TM_USE_TCP_REXMIT_CONTROL must be defined in <trsystem.h> to enable this functionality. The Pause, Resume, and Reset capabilities affect many of the TCP timers. Upper level protocol implementations use their own timers to limit the extent of error-based retries as well. These issues must be considered when using the Pause, Resume, and Reset features else the results may not be as expected.


A Note Regarding Multiple Timers and Pausing

Pausing the TCP Retransmission timer will not only pause TCP-based retries, but also any ZeroWindowProbe messages. The latter is managed by the Window Probe Timer while the former is managed by the Retransmission Timer. When Paused, these timers will not fire however a Resume or Reset operation will immediate retransmit the last message if the timer were to have fired during the Paused period.

Note that during this time the application-level protocol timers continue to run unless they are programmatically suspended as well. Therefore, it's quite possible for a TCP session to abort from the expiration of these timers while the TCP timers are paused.

The TCP Connection Timer is also suspended with a Pause operation. However, unlike other timers, a Resume operation re-computes the amount of time left before the TCP Connection Timer fires before resuming the timer. In this fashion, a TCP Connection Timer requires all of the timeout period to pass while the TCP Retransmission Timer is not Paused.

It is also important to note that the TCP Connection Timer is started with each transmitted packet and uses the Idle Timer (Keep-Alive Timer) to compute whether or not a response has been received in the required timeframe. The Idle Timer, by default, fires after 75 seconds. The TCP Connection Timer, by default, fires after 90 seconds. Of course, line dynamics and the Pause, Resume, and Reset functionality affect these values thus they do not always fire at these intervals. Nonetheless, it is important to note that retuning the TCP Connection Timer may require modifications to the Idle Timer. This is a more advanced topic and casual users should not be concerned with such affairs. In most cases, the default values will prove sufficient.

A Note Regarding Reset

When a Paused Retransmission Timer is Reset, the TCP session is reconfigured as if the packet were being sent for the first time. It is immediately transmitted upon Reset. However, since the Round Trip Time and other parameters required for line timeout values have been reset, it is quite possible for the first retry timeout to differ quite significantly from the timeout period that was being used prior to the Pause. In fact, the timeout will use the defaults that are used when no data has been transmitted for the given socket.


Dynamically Enable/Disable Limited Broadcasts

This feature allows a Treck Option to be set that enables or disables IPv4 Limited Broadcasts. However, this impacts many services such as BOOTP and DHCP that require the use of limited broadcasts and must be disabled with care.


Compile Time Configuration

To enable this capability, you must define TM_USE_LBCAST_CONFIG in <trsystem.h>.


Run Time Configuration

After calling tfStartTreck(), use tfSetTreckOptions() with the TM_OPTION_IP_LBCAST_ENABLE. Set optionValue to 1 (TM_8BIT_YES) to enable Limited Broadcasting (default), or set optionValue to 0 (TM_8BIT_ZERO) to disable Limited Broadcasts.

Dynamically Enable/Disable ICMP Echo Responses

This feature allows a Treck Option to be set that disables IPv4 ICMP Echo Responses. The following sections describe the interface used to for this purpose.


Compile Time Configuration

A macro in <trsystem.h> determines whether IPv4 ICMP Echo Responses can be dynamically enabled or disabled: uncomment TM_USE_ECHO_CONFIG to provide dynamic configuration of IPv4 ICMP Echo replies through the use of the TM_OPTION_ICMP_ECHO_ENABLE option to tfSetTreckOptions().


Run Time Configuration

After calling tfStartTreck(), use tfSetTreckOptions() with the TM_OPTION_ICMP_ECHO_ENABLE optionName. Set optionValue to 1 (TM_8BIT_YES) to enable ICMP Echo Responses (default), or set optionValue to 0 (TM_8BIT_ZERO) to disable ICMP Echo Responses.


Kernel/RTOS Interface


Null Link Layer API


SLIP API


Socket Extension Calls

Timer Interface API


Treck Initialization API


Table of Contents