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.
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"); }
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.
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:
mtcp | mini-TCP and mini-Sockets source files |
mip | mini-IP and UDP source files |
net | network support |
misclib | user interface, mini-IP address parsing code, other similar extra functions |
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:
mcf5223 | Code 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.
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):
listener | A 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 |
tftp | TFTP client and server code |
telnet | Telnet server |
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.
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.
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.
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.
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 |
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 |
The h directory is a system wide include directory. Header files which are used in more than one directory go here.
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 |
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:
|
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. |