Table of Contents

Table of Chapters

1.   OVERVIEW

This programmer's reference is provided with the InterNiche's NicheLite™ TCP/IP stack, as adapted for use with Freescale's 32-bit ColdFire Microprocessors. The purpose of this document is to provide enough information so that a moderately experienced "C" programmer with a reasonable understanding of TCP/IP protocols can develop network-enabled applications.

NicheLite, the InterNiche small footprint TCP/IP stack, is a fully functional replacement for NicheStack™, InterNiche's more traditional full sized stack. Of course some features are removed to achieve the smaller footprint - primarily IP routing at the IP layer, and full BSD sockets API support at the TCP layer.

NicheLite is actually divided into two parts - a mini-TCP layer library, and a mini-IP layer library. The IP layer contains the core IP protocol, ICMP, ARP, UDP, and overhead software for queue and buffer management. The TCP layer contains only the TCP protocol and its mini-sockets API.

This document concerns itself primarily with the mini-Sockets (also known as "the lightweight API), NicheLite's configuration mechanism, and built-in debug tools. When the rest of this document refers to TCP, IP, and Sockets, we are referring to mini-TCP, mini-IP, and mini-Sockets. The code can be found in the mtcp and mip directories.

1.1   Terms and Conventions

In this document the term "stack", when used without further qualification, means the NicheLite software and related code as ported to an embedded system. "System" refers to your embedded system. "Sockets" refers to the mini-TCP API developed for the NicheLite stack. "Porting engineer" refers to the engineer who is porting the InterNiche software to an embedded system. A "user" or "end user" refers to the person who ultimately ends up using the product containing the ported InterNiche software. "FCS" is an acronym for "First Customer Ship", the point in the software development cycle when the product is declared ready to ship. A "packet" is a sequence of bytes sent on network hardware, also known as a "frame" or a datagram".

Names of files, C structures and C routines are displayed as follows: c_routine().

Samples of source code from C programs are displayed in these boxes:

/* C source file - the world's 1 billionth hello program. */
main()
{
   printf("hello world.\n");
}

1.2   TCP/IP Stack Source Code Organization

The source code that a customer receives when they purchase the NicheLite stack is organized into several directories. This section describes this directory structure and the files contained therein.

1.2.1   Target System Independent Directories

Some directories contain code that is relatively target system independent. They contain the implementation of the TCP and IP protocols and the simple user interface. The expectation is that the source code contained in these directories should function with little or no modification on any target.

These directories are briefly described below:

mtcpmini-TCP and mini-Sockets source files
mipmini-IP and UDP source files
netnetwork support
misclibuser interface, mini-IP address parsing code, other similar extra functions

1.2.2   Target System Dependent Directories

Other directories contain code that is relatively target system dependent. They contain code that allows the system independent code to run on a particular class of target systems, effectively providing the "glue layer" for several popular target systems. One such example directory is:

mcf5223Code to support the stack on Freescale MCF5223EVB

These directories contains all of the port-specific code necessary to run NicheLite, with the NicheTask OS on that particular board. If your target system does not match these particulars, it may be used as a "reference point" for modification to your own specific requirements.

Documentation describing the contents of these target system directories is contained in a file, readme.txt, found in the target directory.

1.2.3   Other Product Directories

Other directories will be present when additional InterNiche products are present. The contents of these additional directories are the subject of other InterNiche product documentation. Examples of these directories are listed below (this is not a complete list of other InterNiche products and may not exactly match the your source code distribution):

listenerA simple TCP "listener" which can serve as a starting point for development of a custom application. The example listener listens on port 80 and returns a page using HTTP
tftpTFTP client and server code
telnetTelnet server

1.2.4   Target System Include Directory "h"

Some aspects of a particular target system cannot be easily localized into a single source code directory. These are represented in include files that are included by source files contained in both target system independent and target system dependent directories. ipport.h, which is discussed in greater detail later, is the most widely included example of files of this type but there are others.

Different versions of these target system include files are appropriate for different target systems. Therefore each target system dependent directory contains a set of these files that is appropriate for that specific target system. For example, the mcf5223 directory contains a version of ipport.h that is appropriate for the MCF5223EVB.

1.2.5   Portable Files vs. Port Dependent Files

NicheLite source code files can be categorized according to their degree of portability. "Portable" files are those which should be compiled and used on any target system without modification. "Unportable" or "port dependent" files are those which might need to be modified or replaced for different target systems.

The net, mtcp, and mip directories contain portable files. In general, files whose names include the string "port" that reside in directories containing mostly portable files are the port dependent files. The misclib directory contains both portable and port dependent files.

Target system dependent directories contain primarily port dependent files. The likelihood that these port dependent files will need to be modified for a particular target system is related to how much that target system varies from the target system for which the target system directory was created.

We should point out that our classification of whether a particular file is portable or port dependent is very much a judgment call on our part. When we say that a file is portable, what we mean is that we don't think that it will need to be modified during the porting process, but there is always the possibility that the requirements of a particular target system or application will require that a portable file be modified. Likewise, when we say that a file is port dependent, it does not necessarily mean that the file will need to be modified.

1.3   Overview of NicheLite Stack Source Code Files

This section contains a detailed list of the files contained in the target system independent directories of the NicheLite stack source code. The list is ordered by the directories in which the files reside.

1.3.1   Why Not Modify Portable Files?

As a general rule, it should not be necessary for the porting engineer to modify the portable files.

If, during the course of a routine port, the porting engineer determines that modifications to portable files appear necessary, they should FIRST discuss the intended modifications with the InterNiche technical support staff.

We can either suggest an alternative or modify our sources to reflect a necessary change.

1.3.2   mip Directory Source Files

The mip directory has the stack IP family protocol (ARP, ICMP, UDP) sources:

m_arp.c 
m_icmp.c 
m_ip.c 
m_ipnet.c 
m_udp.c 

1.3.3   net Directory Source Files

The net directory has network support, including pktalloc, queue and dhcp code.

dhcpclnt.c - Optional, needed for DHCP client feature
dhcputil.c - Optional, needed for DHCP client feature
dnsclnt.c 
macloop.c - Optional MAC level loopback driver for testing
udp_open.c 
ping.c - Optional, only needed to support user ping command
pktalloc.c 
q.c 

1.3.4   h Directory Source Files

The h directory is a system wide include directory. Header files which are used in more than one directory go here.

1.3.5   mtcp Directory Source Files

The files in the mtcp directory primarily implement the TCP layer of the NicheLite stack. The portable mtcp directory source files are listed below:

mtcp.h 
tcp_timr.c 
tcpapi.c 
tcpdebug.c 
tcpin.c 
tcpout.c 
tcputil.c 

1.3.6   misclib Directory Source Files

The files in the misclib directory contain code which implements a simple, command-line interface (CLI) that is useful for testing and monitoring the stack software. It also contains useful "utility" functions that did not clearly belong in one of the other directories.

The portable misclib directory source files are listed below:

app_ping.c - implements the functionality of the standard, UNIX ping command that is executable as a menu option from the CLI.
menulib.c - miscellaneous statistics display functions.
menus.c - functions used by the menuing system of the user interface.
nextcarg.c - function used for parsing user interface parameters.
nrmenus.c - contains the definition of the CLI menu structure and many of the functions which implement the menu options. The menu options allow the porting engineer to perform many operations including:    
       
  • Start and stop UDP and TCP echo clients and servers.
  •    
  • Generate an SNMP trap.
  •    
  • Configure the parameters that are stored via the non-volatile storage API.
  •    
  • Dump various internal statistics including information about the ARP cache, buffer queues, HTTP server, network and link layer statistics, Sockets API statistics, IP routing table entries, TCP, UDP, IP and ICMP layer statistics and SNMP MIB counters.
  •    
nvparms.c - functions which parse the contents of an embedded file system into runtime configuration parameters.
parseip.c - used for parsing IP address text.
reshost.c - used by the ping CLI menu option to perform a DNS lookup on a host address.
tcpcksum.c - performs TCP packet checksum calculation.
tcp_echo.c - contains implementations of TCP echo client and server CLI menu options.
udp_echo.c - contains implementations of UDP echo client and server CLI menu options.
userpass.c - performs user and password maintenance for CLI menu options that demonstrate applications that require user authentication.

The port dependent misclib directory source files are listed below:

in_utils.c - mostly contains functions which control how the user interface interacts with the user.
nvfsio.c - includes an implementation of a FLASH file system.
strilib.c 
strlib.c - contains implementations of standard C library string manipulation functions for targets which do not have C libraries that contain these functions.
ttyio.c - implementation of printf() and sprintf() that works in DOS TSRs.