KwikNet TCP/IP Stack USER'S GUIDE Version 3 First Printing: May 15, 1998 Last Printing: September 15, 2005 Manual Order Number: PN303-9 Copyright © 1997 - 2005 KADAK Products Ltd.
TECHNICAL SUPPORT KADAK Products Ltd. is committed to technical support for its software products. Our programs are designed to be easily incorporated in your systems and every effort has been made to eliminate errors. Engineering Change Notices (ECNs) are provided periodically to repair faults or to improve performance. You will automatically receive these updates during the product's initial support period.
Copyright © 1997-2005 by KADAK Products Ltd. All rights reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of KADAK Products Ltd., Vancouver, BC, CANADA. DISCLAIMER KADAK Products Ltd.
Copyright Notice Some components of the KwikNet TCP/IP Stack have been derived from the University of California's Berkeley Software Distribution (BSD). Some components have been adapted from software made available by the Massachusetts Institute of Technology and Carnegie Mellon University. Use of this software requires the following software copyright acknowledgements. Copyright © 1982, 1986 Regents of the University of California All rights reserved.
This page left blank intentionally.
KwikNet TCP/IP Stack User's Guide Table of Contents Page 1. KwikNet Overview 1 1.1 Introduction.......................................................................................... 1.2 General Operation ................................................................................ KwikNet Operation .............................................................................. Multitasking Operation ........................................................................
KwikNet TCP/IP Stack User's Guide Table of Contents (continued) Page 2. KwikNet System Configuration 35 2.1 Introduction.......................................................................................... KwikNet Library.................................................................................. 2.2 KwikNet Configuration Builder........................................................... Starting the Builder ..............................................................................
KwikNet TCP/IP Stack User's Guide Table of Contents (continued) Page 3. KwikNet System Construction (continued) 3.7 Using KwikNet with AMX .................................................................. 3.7.1 AMX System Configuration ............................................................. KwikNet Task ...................................................................................... AMX Interrupt Stack ...........................................................................
KwikNet TCP/IP Stack User's Guide Table of Contents (continued) Page 4. KwikNet Low Level Services (continued) 4.5 KwikNet Network Interface Services................................................... Introduction to Network Interfaces ...................................................... Network Descriptor.............................................................................. Network Parameter Structure (Ethernet).............................................. Network Parameter Structure (SLIP) ....
KwikNet TCP/IP Stack User's Guide Table of Contents (continued) Page 7. KwikNet Virtual File System 239 7.1 Introduction ........................................................................................ VFS File System Structure................................................................... VFS File Names................................................................................... VFS File Operations.............................................................................
KwikNet TCP/IP Stack User's Guide Appendices Page Appendix A. Reference Materials and Glossary A.1 Reference Materials............................................................................. Books ................................................................................................... Internet Sources ................................................................................... A.2 KwikNet Glossary ...............................................................................
KwikNet TCP/IP Stack User's Guide Table of Figures Page Figure 1.2-1 KwikNet Application Block Diagram ................................... Figure 1.2-2 KwikNet Operation ............................................................... 8 9 Figure 2.1-1 Configuring KwikNet ............................................................ Figure 2.2-1 Configuration Manager Screen Layout.................................. 36 38 Figure 3.2-1 KwikNet Library Construction ...........................................
This page left blank intentionally.
1. KwikNet Overview 1.1 Introduction The KwikNet® TCP/IP Stack is a compact, reliable, high performance TCP/IP stack, well suited for use in embedded networking applications. KwikNet is an enhanced version of the Turbo Treck™ TCP/IP Stack, a professional, high-quality networking product created by Treck Inc. The KwikNet TCP/IP Stack includes a complete complement of protocols, some of which are optional.
Installation is delivered to you on a CD-ROM. During installation you will need your CD serial number and product installation key, both of which are recorded on a label attached to the CD-ROM case. The CD serial number is also printed on the face of the CD-ROM. KwikNet KwikNet The CD serial number identifies your KwikNet CD-ROM. The product installation key identifies the specific parts which you are entitled to install from the CD-ROM. is installed by running the InstallShield® SETUP.
Manuals This KwikNet User's Guide describes how KwikNet is used with the standard distribution of Turbo Treck from Treck Inc. It also provides guidance for the correct use of KwikNet with the AMX RTOS. The KwikNet Porting Kit User's Guide describes how KwikNet can be ported for use with any RTOS or for single threaded use. The guide describes how to adapt KwikNet for your particular choice of target processor and how to use you software development tools to construct your KwikNet application.
The KwikNet User's Guide Chapter 1 provides an overview of the KwikNet TCP/IP Stack. The general operation of KwikNet is described and the nomenclature used by KADAK is introduced. Appendix A includes a glossary which will help when you are stuck trying to remember what one of the many protocol mnemonics means. A number of topics unrelated to network issues are covered in this chapter. KwikNet memory allocation requirements are examined.
The Treck TCP/IP User Manual The Treck TCP/IP User Manual provides extensive documentation of the Turbo Treck TCP/IP Stack and the many optional protocol components which it supports. Much of the documentation is tutorial in nature and for this reason deserves careful reading. Chapter 1 provides an excellent introduction to network protocols, what they are and how they are used. Chapter 2 introduces the sockets interface commonly used for programming using the UDP and TCP protocols.
KwikNet provides access to all of the network statistics maintained by the Turbo Treck TCP/IP Stack and it optional components. You can therefore safely ignore the Treck network statistics logging API presented in Chapter 6. The KwikNet TFTP and Telnet clients and servers are not derived from the equivalent Treck components. Hence the description of the Treck TFTP and Telnet options in Chapter 6 can be safely ignored. The KwikNet SMTP client and server are not derived from the equivalent Treck components.
1.2 General Operation The KwikNet TCP/IP Stack and your application operate as illustrated in Figure 1.2-1. If you are using KwikNet with AMX, all of the components shown in the block diagram are provided with KwikNet, ready to use with AMX. You simply provide the application. If you are using the KwikNet Porting Kit to port KwikNet to your operating environment, then the shaded blocks indicate modules which will require modification to adapt KwikNet for use with your application.
Application Application OS Interface KNSAMOS.C KNSAMOS.H OS Interface Module KwikNet TCP/IP Stack KN_OSIF.C KN_OSIF.H RT/OS RT/OS Clock Driver KwikNet Device Driver(s) Board Driver KN_BOARD.C Target Hardware Figure 1.
KwikNet Operation The KwikNet TCP/IP Stack can be used with either a multitasking RTOS or a single threaded operating system. KwikNet and your application operate together as illustrated in Figure 1.2-2. Although the application interface with KwikNet is the same in both cases, the way it executes is quite different. Network Devices ISR Device Driver(s) Clock Interrupt Domain ISR KwikNet Task KwikNet Domain KwikNet Server Task(s) Application Task(s) User Domain or App-Task Figure 1.
Multitasking Operation In a multitasking system which uses an RTOS, operation of the TCP/IP stack is controlled by a single task called the KwikNet Task. This task begins execution after your application calls procedure kn_enter() to start KwikNet. The KwikNet Task executes at a priority above that of all other tasks which use KwikNet services. The KwikNet Task receives timer ticks from the RTOS through the KwikNet OS interface.
Single Threaded Operation Single threaded operation is only supported by KwikNet if you are using the KwikNet Porting Kit. In a single threaded system, there is a single application task which, for reference purposes, is called the App-Task. The App-Task starts in your main() function and executes in what will be referred to as the user domain. Once the App-Task starts, the thread of execution is sequential, flowing back and forth between your application and KwikNet.
Your App-Task can interact with KwikNet using the UDP or IP programming interface or the TCP or UDP socket services. At times, KwikNet will be forced to suspend your App-Task pending completion of a requested service. How this is done depends on the magic of the KwikNet OS interface which ensures that the KwikNet Task continues to service the TCP/IP stack while waiting for the event of interest.
1.3 KwikNet Nomenclature The following nomenclature standards have been adopted throughout this manual. Numbers used in this manual are decimal unless otherwise indicated. Hexadecimal numbers are indicated in the format 0xABCD. Read/write memory is referred to as RAM. Read only memory (non-volatile storage) is referred to as ROM.
1.4 Byte Ordering and Endianness To use a TCP/IP stack, you must adhere to the byte ordering rules defined by the TCP/IP protocol suite. Doing so is complicated by the fact that not all target processors follow these rules. The TCP/IP network uses the big endian model for byte ordering. Sequential bytes in the data stream always appear in sequential bytes in memory. The initial byte of the data stream is at the lowest memory address and the final byte is at the highest memory address.
Net Endian Data provides a set of macros (or functions) which can be used by applications to convert 2-byte (short) values and 4-byte (long) values between net endian form and host endian form. These macros assume the host endianness defined in the KwikNet Network Parameter File. KwikNet The following macros are available in the KwikNet Library.
1.5 Memory Allocation Requirements must be able to dynamically allocate and free blocks of memory of varying sizes. supports three memory allocation strategies using standard C, a simple heap or OS memory management services. KwikNet KwikNet The KwikNet Library must be configured to select one of the three memory allocation strategies. The strategy is defined by the parameters in your Network Parameter File.
OS Memory Management The third memory allocation strategy is to use the memory allocation services provided by the operating system (RT/OS) with which KwikNet is being used. The operating system may have its own private heap from which to allocate memory.
Memory Allocation Protection When operating in a multitasking environment, the memory allocation services must be thread-safe. If the services you have chosen to use are not thread-safe, KwikNet can be configured to use the memory locking mechanism in its OS Interface Module to protect access to the unsafe memory allocation services.
1.6 KwikNet Data Logging Service Like most TCP/IP stacks, KwikNet can generate a variety of messages to assist you in your use of the stack. The messages can provide debug information and trace execution of the stack through its various paths. Your application can also generate a statistics summary of event counts by calling KwikNet procedure kn_netstats(). For debug and trace messages to be generated, the KwikNet Library must be configured accordingly.
Message Print Attributes The parameter defining the message print attributes includes three fields of interest to the user: severity level, class and source type. These fields can be isolated using the following symbolic masks defined in KwikNet header file KN_COMN.H. All other bits in the parameter are reserved for the private use of KwikNet.
KwikNet Data Log Function When message logging is enabled, the KwikNet message generation procedure kn_dprintf() calls the data log function specified in your Network Parameter File. It is the purpose of this function to record (and display or print) the message contained in the KwikNet log buffer which it receives. The Application OS Interface module KNSAMOS.C provided for use with KwikNet sample programs includes a working example of a data log function called sam_record().
1.7 KwikNet Message Recording Service Recognizing that embedded systems may not be able to display or print messages, KADAK provides an alternate message recording service. This service is provided in module KNRECORD.C which is located in the toolset dependent installation directory TOOLXXX\SAM_COMN (see Chapter 3.6). The KwikNet message recording service, used by all KwikNet sample programs, accepts a message contained in a KwikNet log buffer.
1.8 KwikNet Console Driver The KwikNet sample programs provide support for a simple, interactive console device. The console driver, module KNCONSOL.C, is located in the toolset dependent installation directory TOOLXXX\SAM_COMN (see Chapter 3.6). The console driver can be adapted to use any of several possible console devices, including a terminal connected by a serial UART interface, a PC screen and keyboard or a remote Telnet terminal.
Serial I/O Terminal as the Console Device The KwikNet sample program includes a UART serial I/O driver which can be used with the KwikNet console driver to provide access to a terminal. The driver supports the INS8250 (NS16550) USART as implemented in PC compatible hardware. To select this device for console driver use, edit the sample program's application header file KNZZZAPP.H and change the definition of symbol KN_CS_DEVTYPE to be KN_CS_DEVUART.
1.9 Debugging Aids includes a number of debug features which, if used effectively, can help you test your networking application. These features can also be used to provide information to KADAK's technical support staff should you require their assistance. KwikNet KwikNet's debugging services fall into the following categories: debug logging, breakpoint traps and fatal error detection.
Breakpoint Traps can generate a debug trap when it encounters an error condition which is generally not expected in the normal course of events. Such errors are often the result of modifications of private KwikNet data by errant applications which result in decision conflicts which KwikNet cannot resolve. KwikNet debug traps are also generated whenever error reporting is enabled and a warning or error message is generated.
Debug Mask KwikNet maintains a public debug control variable, an unsigned integer named kn_dbgflags. The bits in this variable are used to determine which, if any, KwikNet debug features are enabled at runtime. The bit masks KN_DBxxxxx used to access this variable are defined in KwikNet header file KN_COMN.H. If bit KN_DBENABLE in variable kn_dbgflags is set to 0, all logging of error messages (warnings and fatal error) is disabled.
1.10 KwikNet TCP/IP Sample Program - A Tutorial A TCP/IP Sample Program is provided with KwikNet to illustrate the use of the TCP/IP stack within an application. The sample program is ready for use with the AMX RealTime Multitasking Kernel. The sample program has also been tested with each of the four porting examples provided with the KwikNet Porting Kit. The sample configuration supports a single network interface. The network uses the Ethernet Network Driver.
Startup The manner in which the KwikNet TCP/IP Sample Program starts and operates is completely dependent upon the underlying operating system with which KwikNet is being used. All sample programs provided with KwikNet and its optional components share a common implementation methodology which is described in Appendix E. Both multitasking and single threaded operation are described in detail. When used with AMX, the sample program operates as follows. AMX is launched from the main() program.
Client - Server Using TCP Sockets This example illustrates the use of KwikNet's TCP/IP socket interface to establish a connection between two end points for the reliable transfer of data. Although the end points happen to be tasks running on the same host computer, the actions required by each are still the same as would be required if they resided on separate hosts interconnected by a real network. The server's first scenario is embodied in function server1(). function executed by the client is client1().
The client calls kn_socket() to create a streaming socket. It then calls kn_bind() to bind itself to the socket, allowing KwikNet to assign a port number and IP address. The client then calls kn_connect() to connect to the server with port number 5001 and IP address 192.168.1.73. Note that the client has to know the port number of the server to which it is trying to connect. The IP address of the server happens to be the IP address assigned to the Ethernet network predefined in the KwikNet Library.
Client - Server Using UDP Sockets This example illustrates the use of KwikNet's UDP socket interface to deliver UDP datagrams between two end points. This data transfer mechanism is not considered reliable. Furthermore, since TCP is not used, a logical connection between the end points does not exist. Although the end points happen to be running on the same host computer, the actions required by each are still the same as would be required if they resided on separate hosts interconnected by a real network.
The client then uses procedure kn_select() to wait until some data from the server is available for reading. The sample illustrates the proper use of the macros FD_ZERO, FD_SET and FD_ISSET for manipulating socket sets. The client then uses procedure kn_recv() to receive a 4 byte message, a long value from the server and confirms that the received value is 10, the value sent incremented by 2.
Running the TCP/IP Sample Program The KwikNet TCP/IP Sample Program load module is built just like any other KwikNet application program. The KwikNet Network Parameter File is first created using the KwikNet Configuration Builder as described in Chapter 2. Then the KwikNet Library must be produced. Finally the application must be linked with the KwikNet Library, the RT/OS libraries and the C runtime library to create a load module suitable for testing with a debugger.
2. KwikNet System Configuration 2.1 Introduction Creating an application which uses the KwikNet TCP/IP Stack is a two step process. First, the KwikNet Library must be constructed to reflect the options and features which your application will require. If you wish, you can predefine one or more of the networks and devices present in your target hardware. Finally, your application modules must be linked with the KwikNet Library to create a load module suitable for execution in the target processor.
Enter/Edit/View Network Parameters Configuration Manager Network Parameter File NETCFG.UP Template Files KwikNet Library Make KNnnnLIB.MT Configuration Generator KwikNet Library Header KNnnnLIB.HT KwikNet Library Make File NETCFG.MAK KwikNet Library Header File KN_LIB.H Figure 2.
2.2 KwikNet Configuration Builder The KwikNet Configuration Builder is a software generation tool which can be used to help create your KwikNet Library. You can think of the Builder as a very specialized editor. The Builder consists of two components: the Configuration Manager and the Configuration Generator. The Configuration Manager is an interactive utility which allows you to create and edit your Network Parameter File.
Screen Layout Figure 2.2-1 illustrates the Configuration Manager's screen layout. The title bar identifies the parameter file being created or edited. Below the title bar is the menu bar from which the operations you wish the Manager to perform can be selected. Below the menu bar is an optional Toolbar with buttons for many of the most frequently used menu commands. The Toolbar is hidden or made visible using the View Toolbar command on the Edit menu.
At the bottom of the screen is the status bar. As you select menu items, a brief description of their purpose is displayed in the status bar. If the Configuration Manager encounters an error condition, it presents an error message on the status bar describing the problem and, in many cases, the recommended solution. Along the left margin of the screen are a set of one or more selector icons. These icons identify the type of output files which the Manager can produce from the parameter file being edited.
Field Editing When editing a parameter file, a collection of tabbed property sheets is displayed in the central region of the screen. Each tab provides access to a particular property page through which your configuration parameters can be declared. For instance, if while editing your Network Parameter File, you select the Networks tab, the Configuration Manager will present a network definition window (property page) containing all of the parameters you must provide to completely define a network.
Add, Edit and Delete KwikNet Objects Separate property pages are provided to allow your definition of one or more KwikNet objects such as networks and device drivers. Pages of this type include a list box at the left side of the property page in which the currently defined objects are listed. At the bottom of the list box there may be a counter showing the number of objects in the list and the allowable maximum number of such objects. Also below the list are two control buttons labeled Add and Delete.
This page left blank intentionally.
2.3 KwikNet Library Configuration The KwikNet Library tabbed property sheet is displayed in the central region of the screen. Each tab provides access to a particular property page through which your library configuration parameters can be declared. For instance, if you select the IPv4 tab, the Configuration Manager will present an IPv4 definition window (property page) containing all of the parameters you can adjust to completely define your use of the IPv4 protocol.
Target Parameters The KwikNet Library must be tailored to operate on a particular target processor. These KwikNet parameters are edited using the Target property page. The layout of the window is shown below. Target Processor Select the target processor of interest from those available on the pull down list. Byte Ordering From the pull down list, choose the byte ordering scheme (big endian or little endian) used by the target processor's memory system.
Target Parameters (continued) Data Alignment Boundary From the pull down list, choose the target processor's natural data alignment (16-bit or 32-bit) for long variables and structures. If the natural data alignment is dictated by the processor, this field will be preset and unalterable. Default I/O Method and I/O Cache From the pull down list, choose the method (memory mapped or I/O ports) used for device I/O addressing for the target processor.
OS Parameters The KwikNet Library must be tailored to operate with a particular operating system. These KwikNet parameters are edited using the OS property page. The layout of the window is shown below. Operating System From the pull down list, choose the underlying operating system upon which KwikNet must rely. KwikNet is ready for use without modification with KADAK's AMX kernels. Choose AMX for any of the 32-bit AMX kernels. Choose AMX 86 for 16-bit, real mode operation on any 80x86/88 processor.
OS Parameters (continued) Memory Allocation must be able to dynamically allocate and free blocks of memory of varying sizes. Three methods of memory allocation are supported (see Chapter 1.5). KwikNet Standard C: If you check the "Standard C" radio button, KwikNet will use standard C library functions malloc() and free() to allocate and free memory.
OS Parameters (continued) Source and Size of Memory Region (Heap) If you use the KwikNet simple heap or operating system memory services which require a private region of memory for use as a heap, then you must provide that memory. From the pull down list, choose the method to be used to allocate such a memory region for use by the memory allocator. If you choose the Static array option, you must enter the array size (in bytes) in the Region size field.
OS Parameters (continued) Recycle Without Freeing Memory can recycle memory which it has allocated instead of freeing the memory and having to re-allocate an equivalent sized block of memory at some future time. By recycling allocated memory blocks, KwikNet can improve performance once it reaches a steady state since the need for costly memory allocations is greatly reduced. KwikNet Of course, there is a penalty to be paid for this feature.
General Stack Parameters A number of general network parameters which apply to the complete KwikNet TCP/IP stack are edited using the General property page. The layout of the window is shown below.
General Stack Parameters (continued) Multiple Networks Leave this box unchecked if you have only one network interface through which you can interconnect. Check this box if your application must support more than one network interface. Such configurations are called multi-homed. Enter the maximum number of network interfaces which KwikNet must be able to support. Use Loopback Interface (127.0.0.
General Stack Parameters (continued) KwikNet Optimization The KwikNet Library can be optimized for speed or size. In general, speed improvement comes at the expense of increased code size. Conversely, reducing the memory footprint usually imposes an execution speed penalty. You can choose your optimization preference from the pull down list. KwikNet Shutdown Most embedded applications which incorporate a network stack operate forever once started.
IPv4 Stack Parameters The KwikNet IPv4 Stack parameters are edited using the IPv4 property page. The layout of the window is shown below.
IPv4 Stack Parameters (continued) IP Fragmentation If you wish KwikNet to be able to split IP datagrams for transmission via a network interface or path with a reduced IP data capacity, check this box. Otherwise, leave this box unchecked.
IPv4 Stack Parameters (continued) UDP Channel Support offers a simplified UDP service for those not familiar with the use of the UDP sockets API. The KwikNet UDP service uses a UDP channel, an artificial connection for sending and receiving UDP datagrams (see Chapter 4.1). If you intend to use KwikNet UDP channel services, check this box. Otherwise, leave this box unchecked.
TCP Stack Parameters The KwikNet TCP Stack parameters and socket interface options are edited using the TCP property page. The layout of the window is shown below. Include TCP Check this box if you intend to use the TCP protocol and its KwikNet socket interface. Otherwise, leave this box unchecked to reduce the memory footprint.
TCP Stack Parameters (continued) RFC2018: Selective Acknowledgements This box is normally checked so that KwikNet will follow the selective acknowledgment strategy as documented in RFC2018. Leave this box unchecked to disable this feature. RFC2414: Initial Send Window Increase This box is normally checked so that KwikNet will increase the initial TCP send window as recommended in RFC2414. Leave this box unchecked to disable this feature.
TCP Stack Parameters (continued) Maximum Number of Sockets Enter the maximum number of sockets which your application can have in use at any one time. Remember that a TCP server needs one socket to listen for connection requests and one socket for each accepted connection. Also note that sockets are required for use with UDP or KwikNet UDP channels. Sockets are also used privately by many components of Turbo Treck TCP/IP Stack.
Ethernet Parameters includes an Ethernet network driver which can support multiple Ethernet networks. From the Ethernet property page, you can select the Ethernet network driver for inclusion in the KwikNet Library and edit its operating parameters. The layout of the window is shown below. KwikNet Support Ethernet If you have one or more networks with Ethernet device drivers, check one or both of the Ethernet framing choices to include the KwikNet Ethernet Network Driver in your KwikNet Library.
Ethernet Parameters (continued) Ethernet-II Framing Check this box if you have one or more network interfaces that only support Ethernet-II (DIX) framing. If none of your network interfaces use Ethernet-II (DIX) framing exclusively, leave this box unchecked. This option must be enabled if you plan to create an Ethernet-II network, either dynamically at runtime or by predefining it on the Networks property page.
Ethernet Parameters (continued) Transmit Packet Queue Limit The KwikNet Ethernet Network Driver queues packets for transmission until they can be accepted for transmission by the Ethernet device driver. This parameter defines the maximum number of packets which the network driver will queue. Number of ARP Cache Entries The KwikNet Ethernet Network Driver uses the Address Resolution Protocol (ARP) to associate a specific hardware Ethernet address with a particular IP address.
Point-to-Point (PPP) / SLIP / Modem Parameters has an optional Point-to-Point (PPP) network driver which is capable of supporting multiple PPP networks. The standard KwikNet product includes a SLIP network driver which is capable of supporting multiple SLIP networks. From the PPP/SLIP property page, you can select either of these network drivers for inclusion in the KwikNet Library. This property page is also used to edit the PPP operating parameters. The layout of the window is shown below.
PPP / SLIP / Modem Parameters (continued) Support PPP If you have one or more PPP networks with serial UART device drivers, check this box to force inclusion of the PPP Network Driver in the KwikNet Library. Otherwise, leave this box unchecked. Link Quality Monitoring Check this box to enable use of the Link Quality Protocol for monitoring the quality of the serial communication link. Otherwise, leave this box unchecked.
PPP / SLIP / Modem Parameters (continued) Include Modem Support includes a modem driver for use with any SLIP or PPP network driver. The modem driver can operate concurrently on multiple networks. KwikNet If you have one or more SLIP or PPP networks with serial UART device drivers requiring modem support, check this box to include the KwikNet Modem Driver in your KwikNet Library. Otherwise, leave this box unchecked.
DNS Client Parameters includes an optional DNS Client for accessing Domain Name System services on interconnected networks. The DNS Client is described in Chapter 4.3. The DNS Client is selected and its parameters edited using the Options property page. KwikNet The layout of the Options window is shown below.
DNS Client Parameters (continued) Include DNS Client If your application needs access to Domain Name System services on interconnected networks, check this box. Otherwise, leave this box unchecked. Operating Mode The KwikNet DNS Client will operate in either non-blocking mode or blocking mode. Check the radio button to select the mode in which your application expects to operate when using DNS services.
Optional Components KwikNet includes a variety the Options property page. of client and server options, many of which are selected using The layout of the Options window is shown below. POP3 Client Check this box if your application will include a POP3 client which connects to a POP3 server for mail retrieval operations. Otherwise, leave this box unchecked. MIME Encoding Support Check this box if your application uses MIME encoding and decoding features. Otherwise, leave this box unchecked.
Optional Components (continued) FTP Client Check this box if your application will include an FTP client which connects to an FTP server for file transfers. Otherwise, leave this box unchecked. Check the box labeled "over SSL" if any FTP client will use the Secure Sockets Layer (SSL) for secure file transfers. Otherwise, leave the box unchecked. Note: To use SSL with the FTP client, you require the optional version of the FTP client which includes SSL support.
Debug and Logging Parameters includes a number of debugging and data logging options. These options are enabled and selected using the Debug property page. The layout of the window is shown below.
Debug and Logging Parameters (continued) Informational Messages Check this box to enable informational messages to be generated to help monitor the progress of KwikNet as it executes. If this box is checked, code is inserted into the KwikNet Library to generate progress messages. To omit this code, leave this box unchecked. Error Reporting Check this box to enable warning and error messages to be generated to help identify unexpected problems encountered by KwikNet as it executes.
Debug and Logging Parameters (continued) Enable Message Logging Check this box if you wish to provide a logging function to record (display) text messages generated by KwikNet's data logging services. When this box is checked, you must provide all of the logging parameters listed. If you do not want to provide a logging function, leave this box unchecked. Message Storage Specify the amount of memory to be reserved for use as log buffers.
This page left blank intentionally.
2.4 Adding an Ethernet Network Interface The easiest way to add an Ethernet network interface to your system is to let KwikNet do all of the work. You simply add a description of the network interface and its requirements to your KwikNet User Parameter File and KwikNet prebuilds it for you during its initialization sequence. Of course, you can always dynamically add Ethernet network interfaces at runtime after you start KwikNet.
Ethernet Network Definition (continued) Tag Each network must have a unique network tag. The tag is a string of 1 to 7 characters. This parameter defines that tag. Although KwikNet does not restrict the content of the tag in a network description, the Configuration Manager only supports 1 to 7 ASCII characters as a tag. Edit: Network You must select the Edit: Network radio button to define the network parameters. Network Driver You must select Ethernet-II or Ethernet 802.
Ethernet Device Driver Definition You must define the device driver attached to each prebuilt network which your application supports. A separate device driver definition is required for each prebuilt network. The device driver for each prebuilt network is defined using the Networks property page. The layout of the window is shown below.
Ethernet Device Driver Definition (continued) Tag Each device driver inherits the unique network tag assigned to the network interface to which the device driver is attached. The "Network tag" field defines that tag. Edit: Device You must select the Edit: Device radio button to define the network's device driver parameters. Device Driver To use any of the KwikNet device drivers which are available from KADAK, select its name from the pull down list.
Ethernet IP Address Definition You must provide a network IP address for each prebuilt network which your application supports. The network IP address for each prebuilt network is defined using the Networks property page. The layout of the window is shown below. You can specify a network's IP address using this property page. Alternatively, you can assign the IP address in your network startup hook, if one is provided. Of course, IP addresses can also be assigned dynamically using DHCP, BOOTP or Auto IP.
Ethernet IP Address Definition (continued) IP Version Select the combination of IPv4 and IPv6 protocols that this network interface supports. IPv4 IPv6 All (v4 and v6) Support only IPv4. Support only IPv6. Both IPv4 and IPv6 must be supported. If you select IPv6, be sure to configure your KwikNet Library to include IPv6 support. To do so, check the box labeled "Support IPv6" on the IPv6 property page. Failure to do so will result in a compilation error when you attempt to compile your KwikNet Library.
Ethernet IP Address Definition (continued) Runtime Configuration This parameter is used to select one of the several possible methods for dynamically deriving the network IP address, subnet mask and default gateway for your network. Choose the method from the pull down list. Select None if these parameters are to established according to the definitions which you have entered into the fields on this property page.
This page left blank intentionally.
2.5 Adding a SLIP Network Interface The easiest way to add a SLIP network interface to your system is to let KwikNet do all of the work. You simply add a description of the network interface and its requirements to your KwikNet User Parameter File and KwikNet prebuilds it for you during its initialization sequence. Of course, you can always dynamically add SLIP network interfaces at runtime after you start KwikNet.
SLIP Network Definition (continued) Tag Each network must have a unique network tag. The tag is a string of 1 to 7 characters. This parameter defines that tag. Although KwikNet does not restrict the content of the tag in a network description, the Configuration Manager only supports 1 to 7 ASCII characters as a tag. Edit: Network You must select the Edit: Network radio button to define the network parameters.
SLIP Serial Device Driver Definition You must define the device driver attached to each prebuilt network which your application supports. A separate device driver definition is required for each prebuilt network. The device driver for each prebuilt network is defined using the Networks property page. The layout of the window is shown below.
SLIP Serial Device Driver Definition (continued) Tag Each device driver inherits the unique network tag assigned to the network interface to which the device driver is attached. The "Network tag" field defines that tag. Edit: Device You must select the Edit: Device radio button to define the network's device driver parameters. Device Driver To use any of the KwikNet device drivers which are available from KADAK, select its name from the pull down list.
SLIP IP Address Definition You must provide a network IP address for each prebuilt network which your application supports. The network IP address for each prebuilt network is defined using the Networks property page. The layout of the window is shown below. You can specify a network's IP address using this property page. Alternatively, you can assign the IP address in your network startup hook, if one is provided.
SLIP IP Address Definition (continued) Edit: IP Address You must select the Edit: IP Address radio button to define the network's IP address and related parameters. IP Version SLIP only supports IPv4. Therefore, the IP version selection is not used. Packet Forwarding Select the type of packet forwarding that this network interface supports. Disabled Unicast only Unicast + Dir. Broadcast Forwarding of packets is not allowed on this interface. Support forwarding of IPv4 unicast packets.
2.6 Adding a PPP Network Interface The easiest way to add a PPP network interface to your system is to let KwikNet do all of the work. You simply add a description of the network interface and its requirements to your KwikNet User Parameter File and KwikNet prebuilds it for you during its initialization sequence. Of course, you can always dynamically add PPP network interfaces at runtime after you start KwikNet.
PPP Network Definition (continued) Tag Each network must have a unique network tag. The tag is a string of 1 to 7 characters. This parameter defines that tag. Although KwikNet does not restrict the content of the tag in a network description, the Configuration Manager only supports 1 to 7 ASCII characters as a tag. Edit: Network You must select the Edit: Network radio button to define the network parameters.
PPP Network Definition (continued) Modem Connection The PPP network driver supports remote connections using the KwikNet Modem Driver. Check this box to attach the modem driver to this network. Otherwise, leave this box unchecked. The KwikNet Modem Driver is described in Chapter 1.7 of the KwikNet Device Driver Technical Reference Manual. Note that the network still requires a device driver even if the modem driver is used.
PPP Network Definition (continued) PPP Options Click on the PPP Options... button to open the PPP Options Dialog. Within this dialog you can adjust LCP, authentication and IPCP parameters to meet your PPP requirements. Note that these PPP option settings are for one particular PPP network interface. Different PPP networks can have different option settings. The layout of the PPP dialog box is shown below.
PPP Network Definition (continued) LCP Negotiation Options Header Compression Check this box if the PPP network is permitted to negotiate the use of header compression to reduce the length of the PPP framing header. For most PPP networks, this box should be checked. If you know that the network's peer does not support header compression, leave this box unchecked to avoid the unnecessary negotiation. Magic Number Negotiation Check this box if magic numbers are to be used during LCP negotiation.
PPP Network Definition (continued) IPCP Negotiation Options IP Compression Check this box if the PPP network is permitted to negotiate the use of IP header compression. Either Van Jacobson or IPHC header compression will be used, according to your selection on the PPP/SLIP property page (see Chapter 2.3). If the PPP network must not use IP header compression, leave this box unchecked.
PPP Options (continued) Local IP Address The IP address for each PPP network is usually edited in the network's IP address definition which you access by selecting the Edit: IP Address radio button on the Networks property page. For convenience, the network IP address can also be edited using this PPP Options Dialog. PPP allows the local IP address to be negotiated with the network's peer. If the local IP address is 0.0.0.0, then the local IP address must be negotiated with the peer.
PPP Serial Device Driver Definition You must define the device driver attached to each prebuilt network which your application supports. A separate device driver definition is required for each prebuilt network. The device driver for each prebuilt network is defined using the Networks property page. The layout of the window is shown below.
PPP Serial Device Driver Definition (continued) Tag Each device driver inherits the unique network tag assigned to the network interface to which the device driver is attached. The "Network tag" field defines that tag. Edit: Device You must select the Edit: Device radio button to define the network's device driver parameters. Device Driver To use any of the KwikNet device drivers which are available from KADAK, select its name from the pull down list.
PPP IP Address Definition You must provide a network IP address for each prebuilt network which your application supports. The network IP address for each prebuilt network is defined using the Networks property page. The layout of the window is shown below. You can specify a network's IP address using this property page. Alternatively, you can assign the IP address in your network startup hook, if one is provided, or negotiate the IP address with the network's PPP peer.
PPP IP Address Definition (continued) Edit: IP Address You must select the Edit: IP Address radio button to define the network's IP address and related parameters. IP Version Select the combination of IPv4 and IPv6 protocols that this network interface supports. IPv4 IPv6 All (v4 and v6) Support only IPv4. Support only IPv6. Both IPv4 and IPv6 must be supported. If you select IPv6, be sure to configure your KwikNet Library to include IPv6 support.
PPP IP Address Definition (continued) Default Gateway Check this box if you want the IP address of the foreign host to which the PPP network interface is connected to be used as the default gateway. The default gateway will be set after the PPP network interface has been opened and successfully connected to its peer. The default gateway is used to identify the network interface through which packets are to be sent if the destination IP address is not otherwise known.
2.7 Modem Options If a KwikNet network requires modem support, you must define the modem parameters which govern its use. These modem parameters are edited using the Modem Options Dialog which you access by selecting the Edit: Network radio button and then clicking on the Modem Options... button. The layout of the dialog box is shown below. Startup Hook This parameter provides the name of an application function which will be called when the KwikNet Modem Driver is being initialized.
Modem Options (continued) Connection Method From the pull down list, choose the method by which the modem connection is to be established. Select Modem dialer if the connection will be established using a modem which is initialized using conventional modem commands and their expected modem responses. An optional login script can be used to complete the connection with the remote system after the modem connection has been established. Login scripts are described in Chapter 1.
Modem Options (continued) Initialization String The modem initialization string is sent to the modem before each dialing attempt. The command resets the modem and prepares it for dialing. This string should include the Hayes standard "AT" command prefix. Some common initialization strings are "AT&F" and "ATZ". For more information, consult your modem's reference manual. Telephone Number Enter the telephone number of the remote system to which the modem driver will connect.
This page left blank intentionally.
3. KwikNet System Construction 3.1 Building an Application If you are using KwikNet with AMX or have ported KwikNet to your operating environment, you are now ready to construct the KwikNet Library and build an actual KwikNet application. The sample program(s) provided with KwikNet and its optional components are working examples which you can use either for guidance or as a starting point for your own application. To build a KwikNet application you must perform the following steps. 1.
3.2 Making the KwikNet Library To build the KwikNet Library, you will need a make utility capable of running your C compiler and object librarian (archiver). The library construction process is illustrated in Figure 3.2-1. If you have ported KwikNet to your operating environment, the shaded blocks indicate modules which you have already modified to adapt the make process to accommodate your software development tools. If you are using KwikNet with AMX, these modules are ready for use without modification.
Network Parameter File KwikNet Configuration Builder KwikNet Library Make File KwikNet Source Code Compiler Header KNZZZCC.H OS Interface Module MAKE Utility OS Interface Make File Tailoring File KNZZZCC.INC KN_OSIF.C KN_OSIF.H KN_OSIF.INC C Compiler Object Librarian KwikNet Library Figure 3.
KwikNet Directories and Files The make process depends upon the structure of the KwikNet installation directory KNTnnn. When KwikNet is installed, the following subdirectories are created within directory KNTnnn.
KwikNet Library Make File The KwikNet Configuration Builder is used to create and edit your Network Parameter File, say NETCFG.UP. It is this file which describes the KwikNet options and features which your application requires. From this parameter file, the Configuration Builder generates the KwikNet Library Make File, say NETCFG.MAK. The Library Make File NETCFG.MAK is a make file which can be used to create the Library tailored to your specifications.
Creating the KwikNet Library The KwikNet Library must be constructed from within directory MAKE in the KwikNet installation directory. Your Network Parameter File, say NETCFG.UP, and your Library Make File, say NETCFG.MAK, must be present in the KwikNet MAKE directory. All of the compilers and librarians used at KADAK were tested on a Windows® workstation running Windows NT, 2000 and XP.
3.3 KwikNet Library Compilation Output When you build the KwikNet Library as described in Chapter 3.2, the make utility will transfer files which are unique to KwikNet into the Treck installation directory. If KwikNet is installed in directory C:\KNTnnn and the Turbo Treck TCP/IP Stack is installed in directory C:\TRECK, then all KwikNet header and source files will be copied from directory C:\KNTnnn\TCPIP to the Treck installation directory. Header files will be copied to Treck directory C:\TRECK\INCLUDE.
3.4 Compiling Application Modules In order to compile an application C source file, say MYFILE.C, which makes use of KwikNet services, the following KwikNet header files must be present in the Treck installation directory C:\TRECK\INCLUDE. These files will be copied there, if not already there, whenever a KwikNet Library is built. You must define the path to these header files using compiler switches or environment variables acceptable to your compiler. KN_LIB KN_API KN_COMN KN_OSIF KNZZZCC KN_SOCK .H .H .
3.5 Linking the Application To add KwikNet to your application, you must include the KwikNet Library module KNnnnIP.A in your link specification. Note that library file extensions may be .A or .LIB or some other extension dictated by the toolset which you are using. You must also include the object module for your device driver, say DDRIVER.O, and your KwikNet board support module, say KN_BOARD.O, in your link specification. Note that object file extensions may be .O or .
3.6 Making the TCP/IP Sample Program The KwikNet TCP/IP Stack includes a sample program, a working application that you can use to confirm the operation of KwikNet. Other sample programs are provided for use with optional KwikNet components such as the FTP Option and the Web Server. The KwikNet Application Block Diagram (see Figure 1.2-1 in Chapter 1) summarizes the components which are fundamental to any KwikNet application.
TCP/IP Sample Program Files To build the KwikNet TCP/IP Sample Program using make file KNSAMPLE.MAK, each of the following source files must be present in the indicated destination directory. Source File Destination Directory File Purpose *.* CFGBLDW KwikNet KN_API.H KN_COMN.H KN_OSIF.H KN_SOCK.H KwikNet TCPIP TCPIP TCPIP TCPIP KN_OSIF.INC KNZZZCC.INC KNZZZCC.H TOOLXXX TOOLXXX TOOLXXX KNSAMPLE.MAK KNSAMPLE.C KNZZZAPP.H KNSAMLIB.UP KNSAMPLE.
TCP/IP Sample Program Parameter File The Network Parameter File KNSAMLIB.UP describes the KwikNet options and features illustrated by the sample program. This file is used to construct the KwikNet Library for the TCP/IP Sample Program. The Network Parameter File KNSAMLIB.UP also describes the network interfaces and the associated device drivers which the sample program needs to operate.
The TCP/IP Sample Program Make Process Each KwikNet sample program must be constructed from within the sample program directory in the KwikNet toolset directory. For example, the KwikNet TCP/IP Sample Program must be built in directory TOOLXXX\SAM_TCP. All of the compilers and librarians used at KADAK were tested on a Windows® workstation running Windows NT, 2000 and XP.
3.7 Using KwikNet with AMX 3.7.1 AMX System Configuration includes its own interface to the underlying operating system. The KwikNet OS Interface for AMX is ready for use without modification or customization. KwikNet makes few demands for AMX resources. Consequently, there are few changes to your AMX System Configuration Module required to accommodate KwikNet. KwikNet KwikNet Task A single KwikNet Task drives the KwikNet TCP/IP Stack.
AMX Interrupt Stack You may have to grow the size of your AMX Interrupt Stack, the stack used by all Interrupt Service Procedures. The stack must be large enough to meet the needs of each of the KwikNet device drivers which service your physical network connections. As a good rule of thumb, choose a stack size which is approximately 500 bytes more than the minimum required AMX Interrupt Stack size. KwikNet Semaphores requires one semaphore for its operation.
KwikNet Restart and Exit Procedures You must include KwikNet Restart Procedure kn_osready first (or near first) in your list of Restart Procedures in your AMX System Configuration Module. KwikNet includes a startup procedure kn_enter and a shutdown procedure kn_exit. You can include the KwikNet startup procedure kn_enter in your list of Restart Procedures in your AMX System Configuration Module. It is this procedure which starts the KwikNet Task to initialize the KwikNet TCP/IP Stack.
3.7.2 AMX Target Configuration Each KwikNet device driver for AMX includes an Interrupt Service Procedure consisting of two (sometimes three) parts. All drivers require an ISP root and an Interrupt Handler. Some versions of AMX also require the driver to provide an ISP stem. An ISP root is required for each device interrupt source which the KwikNet board driver module KN_BOARD.C is configured to support.
3.7.3 Toolset Considerations Tailoring Files The KwikNet Library is constructed using your make utility, C compiler and object module librarian. A file which KADAK calls a tailoring file is used to tailor the library construction process for a particular C compiler and object librarian. Separate tailoring files are available for each toolset combination which KADAK supports. These tailoring files are provided ready for use with Microsoft's NMAKE utility.
3.7.4 AMX Application Construction Summary Construction of any KwikNet application for use with AMX will closely follow the steps needed to build the KwikNet TCP/IP Sample Program. These steps are summarized below. Note that the make file provided with KwikNet sample programs actually does steps 5, 6, 7 and 8. 1. Using the KwikNet Configuration Builder, open the Sample Program's Network Parameter File KNSAMLIB.UP (see Chapter 2.3). Use the builder to generate your KwikNet Library Make File KNSAMLIB.MAK.
This page left blank intentionally.
4. KwikNet Low Level Services 4.1 The UDP Programming Interface Applications which are memory constrained or have no need to use TCP can exclude the TCP protocol and use only the KwikNet IP stack and its UDP application programming interface (API). Be aware that UDP is a connectionless protocol which uses only the unreliable IP layer for UDP datagram delivery. There are two ways to access UDP services: use UDP sockets or use UDP channels.
The UDP Channel offers an alternate, low level UDP API which you enable by editing your Network Parameter File and checking the box labeled "UDP channel support" on the IPv4 property page (see Chapter 2.3). KwikNet defines an abstraction called a UDP channel which can be used to control the sending and receiving of UDP datagrams on the network. UDP datagrams cannot be sent without first acquiring a UDP channel. Received UDP datagrams are rejected if an associated UDP channel does not exist.
Receiving UDP Datagrams If you expect to receive a UDP datagram from a foreign host, your open request must provide a pointer to an application callback function which KwikNet can call upon receipt of such a UDP datagram. The callback function is prototyped as follows: int user_udprecv(struct knx_udpmsg *msgp, void *userp); Parameter userp is an application pointer provided by you in your request to open the channel on which this UDP datagram was received.
Processing Received UDP Datagrams Your UDP callback function executes in the context of the KwikNet Task. Your function must not initiate any operation which would force the KwikNet Task to be blocked waiting for some event. In most multitasking applications, it is recommended that your UDP callback function pass the UDP message descriptor to some other application task for processing. Often that task will be the same task that opened the UDP channel and initiated the conversation in the first place.
4.2 DHCP, BOOTP and Auto IP 4.2.1 DHCP and BOOTP includes support for the Dynamic Host Configuration Protocol (DHCP) which permits an Ethernet network's IP address to be dynamically assigned when the network is first started. The DHCP Client which implements this service is provided as a standard feature with systems that only incorporate IPv4. For dual IPv4/IPv6 systems requiring a DHCP Client, an alternate, optional KwikNet DHCP component is available.
DHCP and BOOTP Operation The KwikNet DHCP Client automatically requests an IP address for a DHCP enabled Ethernet network whenever the network interface is opened. The DHCP client uses UDP datagrams for the transmission of DHCP messages. Responses are expected to be in UDP datagrams. The DHCP client broadcasts a DHCP query to all DHCP servers. If the network has been configured for standard DHCP operation and has been configured with an IP address other than 0.0.0.
DHCP Timeout If no response is received from any DHCP or BOOTP server within the timeout interval (initially four seconds), the DHCP client resends its broadcast query and increases its timeout interval by a factor of 2n where n is the number of failed attempts thus far. The retry timeout value is not allowed to exceed an upper limit of 64 seconds. If an IP address cannot be acquired, the DHCP client keeps retrying for approximately three minutes after which the cycle is repeated.
4.2.2 Auto IP Operation There is an optional KwikNet component which provides the Auto IP service which an Ethernet network interface can use to assign its own IP address dynamically when the network is first started. This feature is enabled by a configuration parameter in the KwikNet Network Parameter File used in the construction of the KwikNet Library as described in Chapter 2.3.
4.3 The DNS Client The KwikNet DNS Client is an optional component providing support for the Domain Name System (DNS) which permits a network's IP address to be derived from a name string. For example, the IP address for KADAK's Internet website can be derived by doing a DNS query for the name string www.kadak.com using Treck function tfDnsGetHostByName().
DNS Queries The DNS client will always start a new DNS name lookup by querying the primary DNS server first. If no primary DNS server exists, the query will fail. If the query to the primary DNS server fails, the DNS client will then query the secondary DNS server, if one exists. The results of each DNS query are kept in a name cache maintained by the DNS client. Each cached entry includes one or more of the IP addresses provided by the DNS server which resolved the name.
4.4 ICMP Protocol includes support for the subset of Internet Control Message Protocol (ICMP) services it needs for proper operation of any of the protocols which can be utilized with KwikNet and are dependent on ICMP. KwikNet KwikNet does not issue or reply to timestamp or information requests. supports ICMP destination unreachable datagrams.
This page left blank intentionally.
4.5 KwikNet Network Interface Services Introduction to Network Interfaces Most embedded systems include one or two network interfaces to connect the system to external networks. For such systems, the simplest approach to incorporating the interface into your application is to use the KwikNet Configuration Builder to add the network interface to your KwikNet Library.
Network Descriptor When a network interface is added with a call to kn_ifadd(), KwikNet allocates a network descriptor structure which it uses to define the network. A pointer to the structure is returned to the caller as a handle for subsequent references to the interface. The handle is called a network descriptor pointer and is declared to be of type KN_NETDP.
Network Parameter Structure When a network interface is opened with a call to kn_ifopen(), KwikNet configures the interface according to your definition of the operating characteristics required for that network. The parameters are presented in a network parameter structure. A separate structure is defined for each type of network interface in KwikNet header file KN_API.H.
Network Parameter Structure (SLIP) struct knx_np_slip struct in_addr struct in_addr struct in_addr short short }; { xp_slip_ipaddr; xp_slip_ipremote; xp_slip_unused; xp_slip_ipattr; xp_slip_rsv1; /* /* /* /* /* Network IP address Remote peer IP address Reserved field IP address attributes Reserved for alignment */ */ */ */ */ For SLIP networks, a valid local IP address must be defined. A remote peer IP address must be provided for routing purposes. If the remote peer IP address is specified as 0.0.0.
Network Parameter Structure (PPP) struct knx_np_ppp { struct in_addr xp_ppp_ipaddr; struct in_addr xp_ppp_ipremote; struct in_addr xp_ppp_unused; short xp_ppp_ipattr; short xp_ppp_rsv1; unsigned long xp_ppp_options; struct in_addr xp_ppp_dns1; struct in_addr xp_ppp_dns2; }; /* /* /* /* /* /* /* /* Network IP address Remote peer IP address Reserved field IP address attributes Reserved for alignment Negotiation options Primary DNS IP address Secondary DNS IP address */ */ */ */ */ */ */ */ For PPP network
Network Attributes Each network parameter structure includes a field which is used to specify the network interface attributes. The structure name, field name and allowable attributes are dependent upon the interface type. Interface Ethernet SLIP PPP Structure Field knx_np_ether knx_np_slip knx_np_ppp xp_ether_ipattr xp_slip_ipattr xp_ppp_ipattr The network attributes are specified by ORing the value 0 with one or more of the following attribute bit masks from KwikNet header file KN_COMN.H.
Network States A network interface is always in one of three states. The interface is down when first added to the KwikNet list of network interfaces. The network goes in transit as soon as the network is opened. The network stays in transit until a valid IP address has been assigned to the network interface at which point the network is declared up. The network remains up until you close it at which time it once again goes in transit.
Starting and Stopping KwikNet Most applications start KwikNet with a call to kn_enter() and allow KwikNet to run forever. Some use kn_exit() to stop KwikNet in preparation for a termination of the entire application. Others find it necessary to stop and then restart KwikNet to recover from serious network faults. The ability to start and stop KwikNet on demand is also useful when testing your network application. is started with a call to kn_enter().
4.6 KwikNet Library Services The KwikNet Library provides a set of network services from which the real-time system designer can choose. Many of the services are optional and, if not used or configured into your KwikNet Library, will not even be present in your final KwikNet system. The following list summarizes the KwikNet low level service procedures which are accessible to the user. These procedures are all present in the KwikNet Library. They are grouped functionally for easy reference.
The following BSD-like services are also available in the KwikNet IP Library.
KwikNet Procedure Descriptions A description of all KwikNet low level service procedures is provided in this chapter. The descriptions are ordered alphabetically for easy reference. All of the KwikNet procedures are described using the C programming language. Italics are used to distinguish programming examples. Procedure names and variable names which appear in narrative text are also displayed in italics.
KwikNet Procedure Descriptions (continued) Used by n Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure For other multitasking systems, a task is any application task executing at a priority below that of the KwikNet Task. A Timer Procedure is a function executed by a task of higher priority than the KwikNet Task. An ISP is a KwikNet device driver interrupt handler called from an RTOS compatible interrupt service routine. The other procedures do not exist.
hton– ntoh– hton– ntoh– Purpose Convert Between Host and Network Endian Forms Used by n Setup The macro definitions are in file KN_LIB.H. C dependent, in-line assembly language expansions are in file KNZZZCC.H. Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure #include "KN_LIB.
kn_addserver kn_addserver Purpose Install (Add) a Server Function Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" void kn_addserver(struct knx_svblock *servercbp, unsigned long period, int (*serverfnp)(void *), void *param); Description Servercbp Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a pointer to a KwikNet server control block which KwikNet can use to control the periodic execution of this server function.
kn_cksum kn_cksum Purpose Compute an IP Checksum Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" unsigned short kn_cksum(void *p, unsigned int n); Description P is a pointer to a 16-bit aligned region of memory containing an array of 16-bit unsigned short integers to be checksummed. N is the number of 16-bit unsigned short integers in the memory array referenced by pointer p.
kn_dprintf kn_dprintf Purpose Format and Log a Text Message Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" void kn_dprintf(int attrib, const char *fmtp, ...); Description Attrib Task o ISP o Timer Procedure n Restart Procedure n Exit Procedure is a parameter which defines the message attributes. Applications should use the value of 0 for attrib. Valid attributes are described in Chapter 1.6.
kn_enter kn_exit kn_enter kn_exit Purpose Launch or Terminate the KwikNet TCP/IP Stack Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" void kn_enter(void); void kn_exit(void); Description Procedure kn_enter() must be called to launch (start) the KwikNet TCP/IP Stack. Task o ISP o Timer Procedure n Restart Procedure n Exit Procedure Procedure kn_exit() must be called to terminate (stop) the KwikNet TCP/IP Stack.
kn_fmt kn_fmt Purpose Format a Text String Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_fmt(char *bufp, const char *fmtp, ...); Description Bufp o Task ISP o Timer Procedure n Restart Procedure n Exit Procedure is a pointer to storage for the formatted string. is a pointer to a format specification string similar to that expected by the C library procedure printf(). Allowable format specifications are summarized on the next page.
Formats ...continued Allowable format specification strings must be of the form "...%-0##z?...
kn_godown kn_godown Purpose Initiate a Shutdown of the KwikNet TCP/IP Stack Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_godown(int timeout); Description Timeout Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is the maximum interval, measured in seconds, which the caller is willing to wait for the KwikNet shutdown to complete. If timeout is 0, the caller will wait forever or until an error condition is detected.
kn_ifadd kn_ifadd Purpose Add a Network Interface Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" KN_NETDP kn_ifadd(KN_FNP_NETPREP netprepp, const struct knx_dvcdef *ddefp); Description netprepp Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a pointer to a network preparation function which will be used by KwikNet to prepare a network interface for use.
kn_ifaddress kn_ifaddress Purpose Get the IP Address for a Network Interface Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_ifaddress(KN_NETDP netdp, struct in_addr *inadrp); Description Netdp Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a network descriptor pointer, the KwikNet handle used to identify the network interface of interest. is a pointer to a structure into which the network's IPv4 address in net endian form will be stored.
kn_ifclose kn_ifclose Purpose Close a Network Interface Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_ifclose(KN_NETDP netdp); Description Netdp Returns If the network interface is successfully closed or was already closed, a value of 0 is returned. Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a network descriptor pointer, the KwikNet handle used to identify the network interface of interest.
kn_iffind kn_iffind Purpose Find a Network Interface with a Specific Network Tag Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" KN_NETDP kn_iffind(const char *nettag); Description Nettag Returns If successful, the network descriptor pointer for the network interface is returned. This KwikNet handle can be used to identify the network interface in subsequent calls to KwikNet procedures.
kn_ifinfo kn_ifinfo Purpose Fetch Information About a Network Interface Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_ifinfo(KN_NETDP netdp, struct knx_ifinfo *infop); Description Netdp Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a network descriptor pointer, the KwikNet handle used to identify the network interface of interest.
kn_ifmodem kn_ifmodem Purpose Attach the Modem Driver to a Network Interface Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_ifmodem(KN_NETDP netdp, const struct knx_mdmdef *mdefp); Description Netdp Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a network descriptor pointer, the KwikNet handle used to identify the network interface of interest.
kn_ifnethook kn_ifnethook Purpose Register a Network Hook Function for a Network Interface Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_ifnethook(KN_NETDP netdp, KN_FNP_NETHOOK nethookfn); Description Netdp Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a network descriptor pointer, the KwikNet handle used to identify the network interface of interest. Parameter nethookfn is a pointer to your network hook function.
kn_ifnext kn_ifnext Purpose Find the Next Available Network Interface Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" KN_NETDP kn_ifnext(KN_NETDP netdp); Description Netdp Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a network descriptor pointer, the KwikNet handle used to identify the currently selected network interface of interest. If netdp is NULL, the first available network interface will be selected.
kn_ifopen kn_ifopen Purpose Open a Network Interface Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_ifopen(KN_NETDP netdp, void *paramp); Description Netdp Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a network descriptor pointer, the KwikNet handle used to identify the network interface of interest. Parameter paramp is a pointer to a network parameter structure which specifies the configuration parameters for the network interface.
kn_ifstate kn_ifstate Purpose Query the State of a Network Interface Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_ifstate(KN_NETDP netdp); Description Netdp Returns If successful, one of the following constant values will be returned. KN_NIFS_DOWN The network was down and unavailable for use. KN_NIFS_TRANSIT The network was in the process of going up or down. KN_NIFS_UP The network was up with a valid IP address.
kn_inet_addr kn_inet_addr Purpose Convert a Dotted Decimal IP Address to Numeric Form Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_inet_addr(const char *sp, struct in_addr *inadrp); Description Sp Task o ISP o Timer Procedure n Restart Procedure n Exit Procedure is a pointer to a string containing an IPv4 address in dotted decimal form. The string does not have to be terminated by '\0'. Leading whitespace before the numbers in the IP address will be ignored.
kn_inet_ntoa kn_inet_ntoa Purpose Convert a Numeric IP Address to Dotted Decimal String Form Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_inet_ntoa(struct in_addr *inadrp, char *sp); Description Inadrp Task o ISP o Timer Procedure n Restart Procedure Exit Procedure is a pointer to a structure containing an IPv4 address in net endian form. The BSD structure in_addr is defined in Treck header file TRSOCKET.
kn_logbuffree kn_logbuffree Purpose Free a KwikNet Log Buffer Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" void kn_logbuffree(char *bufp); Description Bufp Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a pointer to the KwikNet log buffer which is to be freed. This is a buffer allocated by KwikNet from its private pool of log buffers in response to a request to log a message.
kn_netevent kn_netevent Purpose Notify Application of Significant Network Event (User Function) Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" void kn_netevent(KN_NETDP netdp, int eventid); Description KwikNet Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure calls this user function whenever a signficant network event has been detected. Your application must provide this function.
kn_netstats kn_netstats Purpose Log KwikNet Network Statistics Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" void kn_netstats(unsigned long statmask); Description KwikNet Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure will log network statistics which it has been gathering. The information is formatted into log buffers and presented a line at a time to your data logging function (see Chapter 1.6).
kn_panic 170 kn_panic Purpose Generate a KwikNet Fatal Error Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" void kn_panic(const char *msgp); Description Msgp Returns Never See Also kn_exit() Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a pointer to a message string to be logged by KwikNet before it initiates a fatal shutdown of the underlying RT/OS.
kn_state kn_state Purpose Sense the Operating State of the KwikNet TCP/IP Stack Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" unsigned int kn_state(unsigned int wstate, unsigned long mswait); Description This function can be used to determine the current operating state of KwikNet or to wait until KwikNet reaches a particular state.
kn_udpbind kn_udpbind Purpose Bind a Local IP Address and Port to a UDP Channel Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_udpbind(unsigned long udphandle, struct in_addr *lhostp, int lport); Description Udphandle is a kn_udpopen().
kn_udpclose kn_udpclose Purpose Close a UDP Channel Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_udpclose(unsigned long udphandle); Description Udphandle is a kn_udpopen(). Returns If successful, a value of 0 is returned. On failure, the error status -1 is returned. Example See example in the description of kn_udpopen().
kn_udpfree 174 kn_udpfree Purpose Free a Received UDP Message Packet Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" void kn_udpfree(struct knx_udpmsg *msgp); Description Msgp Returns Nothing Example See example in the description of kn_udpopen(). See Also kn_udpopen() Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a pointer to the UDP message descriptor given to your application's UDP callback function upon receipt of a UDP datagram.
kn_udpopen kn_udpopen Purpose Open a UDP Channel to Send/Receive UDP Datagrams on a Network Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.
Description ...continued is the name of your application callback function which will be called to process received UDP datagrams. Your function will receive parameter msgp, a pointer to a UDP message descriptor. The second parameter, userp, is a copy of the pointer variable userp received as a parameter in this kn_udpopen() procedure call. Udprcv Your UDP callback function must be coded as described in Chapter 4.1. The callback function must return -1 if it cannot accept the message descriptor.
...continued Example #include "kn_lib.
kn_udpsend kn_udpsend Purpose Send a UDP Datagram on a Network Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_udpsend(unsigned long udpchannel, struct in_addr *fhostp, int fport, char *bufp, int length); Description Udpchannel is a kn_udpopen().
kn_yield kn_yield Purpose Yield to the KwikNet Task Used by n Setup Prototype is in file KN_API.H. #include "KN_LIB.H" int kn_yield(void); Description Your single threaded application must regularly yield to the KwikNet Task. Failure to yield at least at the defined KwikNet clock frequency may result in poor performance of the TCP/IP stack. Returns Error status is returned.
ntoh– hton– ntoh– hton– Purpose Convert Between Network and Host Endian Forms Used by n Setup The macro definitions are in file KN_LIB.H. C dependent, in-line assembly language expansions are in file KNZZZCC.H. Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure #include "KN_LIB.
5. KwikNet TCP/IP Sockets 5.1 Introduction to KwikNet Sockets Sockets is an application programming interface (API) which was developed for UNIX during the early 1980s at University of California, Berkeley. It is primarily used today for TCP programming. Dozens of books and tutorials are available for sockets programming, one of the compelling arguments for the use of sockets. Programmers new to sockets may observe that the sockets API seems unnecessarily complex. The reasons are historical.
KwikNet Sockets API The KwikNet TCP sockets API is a subset of that available on UNIX systems. Examples of networking code from other sockets-based systems can be expected to port easily. Furthermore, most of the reference material in books and tutorials will also apply to the KwikNet API. The KwikNet API has been designed for best use in embedded systems where execution speed, code size and ease of use are of paramount importance.
Non-Blocking Sockets When operations are performed using a socket, the caller requesting the action is usually forced to wait until the operation completes. The socket is said to be in blocking mode. offers an alternative mode of operation in which the socket action is allowed to proceed without blocking the caller. In this case, the socket is said to be in non-blocking mode. KwikNet When a socket is created it is placed in blocking mode.
5.2 Socket Types Procedure kn_socket() is used to create a socket. The KwikNet TCP/IP Stack only supports sockets for use in the communication domain which uses the protocol family known as the ARPA Internet Protocol, identified as PF_INET . Two socket types are supported: type SOCK_STREAM for use with the TCP protocol and type SOCK_DGRAM for use with the UDP protocol. Stream Socket (for TCP) A socket of type SOCK_STREAM provides a sequenced, reliable, full duplex connection between two end points.
Functions kn_writev() and kn_readv() can also be used to send and receive data. If you have provided a destination address with a kn_connect() call, you can use function kn_send() to send data to that destination. And you can always use function kn_recv() to receive data, as long as you do not need to identify the source.
UDP Sockets Examples The following examples illustrate how a UDP socket can be used in a variety of circumstances for different purposes. Example 1 To use a UDP socket to communicate on a specific network with one and only one foreign host, proceed as follows. Create a UDP socket and use kn_bind() to bind it to a specific local IP address and port. Then call kn_connect() to establish a logical connection with the foreign host's IP address and port.
5.3 Socket Options The operation of sockets is controlled by socket level options. Options are always present at the socket level identified as SOL_SOCKET. KwikNet also supports TCP options at protocol level IPPROTO_TCP. There are no UDP protocol options. The KwikNet options are listed in file KN_SOCK.H but are defined in Treck file TRSOCKET.H. Procedures kn_getsockopt() and kn_setsockopt() are used to access and modify these options. The following commonly used options are recognized by KwikNet.
Option SO_BROADCAST requests permission to send broadcast datagrams on the socket. Option SO_OOBINLINE, used with protocols that support out-of-band data, requests that out-of-band data be placed in the normal data queue as it is encountered. The data will then be accessible with the kn_recv() call without the need to specify the MSG_OOB flag. Option SO_LINGER controls the action taken when unsent messages remain queued on a socket at the time a kn_close() request to delete the socket is made.
Non-Standard Socket Options The non-standard option SO_NONBLOCK can be used to set a socket into non-blocking mode so that the socket user will not be forced to wait if a requested operation cannot be completed at the time of the request. It can also be used to restore a socket to blocking mode so that the socket user will be forced to wait until the requested operation completes. This option's integer parameter is non-zero for non-blocking mode or zero for blocking mode.
This page left blank intentionally.
5.4 KwikNet Socket Services KwikNet Socket Service Summary The following list summarizes all of the KwikNet sockets procedures which are accessible to the user. They are grouped functionally for easy reference.
This page left blank intentionally.
kn_accept kn_accept Purpose Accept a Connection Request Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_accept(int s, struct sockaddr *addr, int *addrlen); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the socket on which to wait.
Returns ...continued The error indicator for socket s is set to define the reason for failure. Use to retrieve the error code. kn_errno() EBADF EINVAL ECONNABORTED ENOBUFS EOPNOTSUPP EPERM EWOULDBLOCK See Also 194 The socket descriptor s is invalid. Parameter addr or addrlen is invalid or parameter *addrlen specifies a length that is less than that required to accommodate a valid address or the socket is no longer accepting connections. The connection was aborted.
kn_bind kn_bind Purpose Bind a Local Address to a Socket Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_bind(int s, struct sockaddr *localaddr, int addrlen); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the socket to be bound. is a pointer to a structure containing the local address to which the socket must be bound.
kn_close kn_close Purpose Close a Socket Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_close(int s); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the socket to be closed. When a socket is closed, associated naming information and queued data are discarded. Returns If successful, a value of 0 is returned. On failure, the error status -1 is returned.
kn_connect kn_connect Purpose Connect a Socket to a Specific Address Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_connect(int s, struct sockaddr *destaddr, int addrlen); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the socket to which the specified address is to be bound. is a pointer to a structure containing the specific address to which the socket must be bound.
Returns ...continued The error indicator for socket s is set to define the reason for failure. Use to retrieve the error code. kn_errno() EBADF EINVAL EADDRNOTAVAIL EADDRINUSE EAFNOSUPPORT ETIMEDOUT ECONNREFUSED EHOSTUNREACH EINPROGRESS EALREADY EPERM ENOBUFS ** note ** See Also 198 The socket descriptor s is invalid. The socket is already bound to an address or parameter destaddr or addrlen is invalid.
kn_errno kn_errno Purpose Get Error Code from Recent Socket Operation Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_errno(int s); Description S Returns If successful, a positive error code is returned. These error codes are summarized in Appendix B. The error code identifies the reason for the failure, if any, of the most recent operation attempted using socket s.
kn_getpeername kn_getpeername Purpose Get the Address (Name) of the Remote End of a Connected Socket Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_getpeername(int s, struct sockaddr *destaddr, int *addrlen); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the socket for which the remote end (peer) address is desired.
kn_getsockname kn_getsockname Purpose Get the Local Address (Name) of a Socket Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_getsockname(int s, struct sockaddr *localaddr, int *addrlen); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the socket for which the local address is desired.
kn_getsockopt kn_getsockopt Purpose Get a Particular Socket Option Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_getsockopt(int s, int level, int optionid, void *optionval, int *optionlen); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the socket for which the particular socket information is desired. is an identifier indicating the socket or protocol level for which information is required.
Description ...continued is a pointer to storage for the option value. The size of each option is indicated in the option list. Note that bool is an int result that is 1 if the option is enabled or 0 if the option is disabled. The type u/s long indicates a 32-bit value usually represented by an unsigned long. The structure linger required by option SO_LINGER is described in header file KN_SOCK.H. Optionval is a pointer to storage for the length of the returned option value.
kn_listen kn_listen Purpose Request a Socket to Listen for Connection Requests Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_listen(int s, int backlog); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the socket on which requests for connection will be enqueued. The socket s must have been created with a call to kn_socket() and bound to an address with a call to kn_bind().
kn_readv kn_readv Purpose Receive Scattered Data from a Socket Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_readv(int s, struct iovec *iovecp, int iovcnt); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the socket from which data is to be received. The socket must be connected. is a pointer to an array of data vectors describing the locations of storage buffers for the received data.
Returns ...continued The error indicator for socket s is set to define the reason for failure. Use to retrieve the error code. kn_errno() EBADF EINVAL ENOTCONN EWOULDBLOCK ESHUTDOWN ENOBUFS 206 The socket descriptor s is invalid. Parameter iovecp or iovcnt is invalid or the buffer length in a data vector was declared to be less than 0 or the sum of the data vector lengths exceeds the maximum size of an integer. The socket is not connected.
kn_recv kn_recv Purpose Receive Data from a Connected Socket Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_recv(int s, void *buf, int len, int flags); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the connected socket from which data is to be received. Note that the socket must be connected either by calling kn_connect() to connect or by calling kn_accept() to accept a connected socket.
208 Restriction If there is no data available at the socket, the caller will be blocked waiting for data to arrive unless the socket s is marked as non-blocking. In the latter case, the caller will resume with a -1 error status and the error code EWOULDBLOCK will be stored in the socket descriptor.
kn_recvfrom kn_recvfrom Purpose Receive Data from a Socket Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_recvfrom(int s, void *buf, int len, int flags, struct sockaddr *from, int *fromlen); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the socket from which data is to be received. The socket can be connected or unconnected. Buf is a pointer to storage for the received data.
Returns If successful, the number of bytes of data stored at *buf is returned. If the socket is closed by the sender, the value 0 is returned. The structure at *from contains the sender's address. The storage at *fromlen is set to the actual size of the address. On failure, the error status -1 is returned. The storage at *from and *fromlen may be altered. The error indicator for socket s is set to define the reason for failure. Use kn_errno() to retrieve the error code.
kn_select kn_select Purpose Select Sockets Ready for Receive or Send Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_select(int nfds, fd_set fd_set fd_set struct Description Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure *readfds, *writefds, *exceptfds, timeval *timeout); indicates the number of sequential socket descriptors which are to be examined in each descriptor set.
Description ...continued is a pointer to a structure which defines the interval for which the caller is prepared to wait for at least one socket to meet the selected criteria. The timing resolution is determined by the KwikNet clock frequency. Set timeout to NULL to wait forever. Set the interval value to 0 to return immediately if no sockets are ready. If the specified timeout interval is less than one millisecond, the procedure will return immediately with a timeout indication if no sockets are ready.
Returns If successful, this procedure returns the total number of ready sockets identified in the descriptor sets. The variables *readfds, *writefds and *exceptfds are updated to identify the subset of the sockets specified by the caller which match their respective criteria. This procedure returns 0 if the specified timeout interval elapses before any sockets are ready. On failure, the error status -1 is returned. Unfortunately, the error indicator defining the reason for failure cannot be recorded.
kn_send kn_send Purpose Send Data to a Connected Socket Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_send(int s, void *buf, int len, int flags); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the connected socket to which data is to be sent. Buf is a pointer to the buffer of data to be sent. Len is the buffer size, measured in bytes.
Restriction If none of the message data can be delivered to the socket, the caller will be blocked unless the socket s is marked as non-blocking. In the latter case, the caller will resume with a -1 error status and the error code EWOULDBLOCK will be stored in the socket descriptor.
kn_sendto kn_sendto Purpose Send Data to a Socket Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_sendto(int s, void *buf, int len, int flags, struct sockaddr *to, int tolen); Description S o Task ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the socket to which data is to be sent. The socket can be connected or unconnected. Buf is a pointer to the buffer of data to be sent.
Returns If successful, the number of bytes of data sent from *buf is returned. On failure, the error status -1 is returned. The error indicator for socket s is set to define the reason for failure. Use kn_errno() to retrieve the error code. EBADF EINVAL EMSGSIZE EPROTOTYPE EHOSTUNREACH EWOULDBLOCK ENOBUFS The socket descriptor s is invalid.
kn_setsockopt kn_setsockopt Purpose Set a Particular Socket Option Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_setsockopt(int s, int level, int optionid, void *optionval, int optionlen); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the socket for which the particular socket option is to be modified.
Description ...continued is a pointer to the option value. The size of each option is indicated in the option list. Note that bool is an int value that is 1 if the option is to be enabled or 0 if the option is to be disabled. The type u/s long indicates a 32-bit value usually represented by an unsigned long. The structure linger required by option SO_LINGER is described in header file KN_SOCK.H. Optionval Optionlen is the optionval.
kn_shutdown kn_shutdown Purpose Shut down All or Part of a Full Duplex Socket Connection Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_shutdown(int s, int how); Description S Task o ISP o Timer Procedure o Restart Procedure o is a socket descriptor identifying the socket with the connection which is to be shut down.
kn_socket kn_socket Purpose Create a Socket (an Endpoint for Communication) Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_socket(int domain, int type, int protocol); Description Domain Task o ISP o o Timer Procedure Restart Procedure o Exit Procedure specifies the communications domain within which communication will occur. The domain identifies the protocol family which should be used.
Returns If successful, a non-negative socket descriptor is returned. On failure, the error status -1 is returned. If a socket cannot be created, the error indicator defining the reason for failure cannot be recorded. You cannot use kn_errno() to retrieve the error code since you have no socket descriptor to interrogate. The following error codes, although not available for testing, still define the possible reasons for failure.
kn_writev kn_writev Purpose Send Scattered Data to a Socket Used by n Setup Prototype is in file KN_SOCK.H. #include "KN_SOCK.H" int kn_writev(int s, struct iovec *iovecp, int iovcnt); Description S Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is a socket descriptor identifying the socket to which data is to be sent. The socket must be connected. is a pointer to an array of data vectors describing the locations of the data to be sent.
Returns ...continued The error indicator for socket s is set to define the reason for failure. Use to retrieve the error code. kn_errno() EBADF EINVAL EMSGSIZE ENOTCONN EWOULDBLOCK ESHUTDOWN ENOBUFS 224 The socket descriptor s is invalid. Parameter iovecp or iovcnt is invalid or the buffer length in a data vector was declared to be less than 0 or the sum of the data vector lengths exceeds the maximum size of an integer.
6. KwikNet PPP Option 6.1 Introduction to PPP The Point-to-Point Protocol (PPP) is a network protocol used to control the delivery of IP datagrams between two host computers interconnected by a serial link. The KwikNet PPP option adds this protocol to the KwikNet TCP/IP Stack, a compact, reliable, high performance TCP/IP stack, well suited for use in embedded networking applications.
Beyond the summary above, this manual makes no attempt to describe the Point-to-Point Protocol (PPP), what it is or how it operates. It is assumed that you have a working knowledge of the PPP protocol as it applies to your needs. Reference materials are provided in Appendix A. The purpose of this manual is to provide the system designer and applications programmer with the information required to properly configure and implement a networking system using the KwikNet TCP/IP Stack and PPP.
6.2 KwikNet PPP Configuration You can readily tailor the KwikNet stack to accommodate your PPP needs by using the KwikNet Configuration Builder to edit your KwikNet Network Parameter File. The KwikNet Library parameters are edited on the PPP/SLIP property page. The PPP parameters have been defined in Chapter 2.3. The layout of the window is repeated below for convenience.
PPP Network Definition You must define each PPP network which your application must support. A separate definition is required for each such network. The total number of networks must not exceed the maximum number of networks which your KwikNet Network Parameter File allows. A PPP network can be defined using the Networks property page as described in Chapter 2.6. The layout of the window is repeated below for convenience.
PPP Options For each KwikNet network which supports PPP, you must define the PPP parameters which govern its use. These PPP option parameters can be edited using the PPP Dialog Box entered via the PPP Options... button on the Networks definition property page. These PPP options have been described in Chapter 2.6. The layout of the dialog box is repeated below for convenience.
6.3 Using a PPP Network Interface The PPP Client and Server The easiest way to add a PPP network interface to your KwikNet application is to use the KwikNet Configuration Manager to specify the network in your Network Parameter File. Each network interface defined in this manner is automatically prebuilt for you whenever KwikNet starts. However, your application can dynamically add a PPP network interface at runtime by calling KwikNet procedure kn_ifadd().
Opening a PPP Network Interface The KwikNet PPP network driver supervises the orderly opening of the PPP network interface. During the opening process, your application is given several opportunities to adjust the manner in which the PPP connection is eventually established. The network driver calls the network startup hook, if one has been configured for use by the network interface. The startup hook is specified in the network definition for prebuilt PPP networks.
6.4 PPP Authentication Parameters If any of your PPP networks require PAP, CHAP, MS-CHAP or EAP authentication, you must provide the KwikNet PPP network driver with access to the authentication parameters needed to support these protocols. These parameters are the heart of your PPP security system. The maintenance and safekeeping of these parameters is your responsibility. The KwikNet PPP authentication parameters for each PPP network interface are located in array kn_ppp_auth[] in module KN_PPPAA.
File KN_PPPAA.C provides the authentication parameters for one user on a single PPP network interface. You must edit this module to define the authentication parameters which apply to each of your PPP network interfaces. The KwikNet PPP network driver accesses these authentication parameters by calling the KwikNet PPP administration function kn_ppp_admin() within module KN_PPPAA.C. You must review this function and, if necessary, alter it to meet your specific requirements.
kn_ppp_admin kn_ppp_admin Purpose Provide PPP Authentication Services Context n Setup Prototype and definitions are in file KN_API.H. Structure definitions are in file KN_PPPAA.C. KwikNet Task n Application Task #include "KN_LIB.H" #include "KN_NET.H" int kn_ppp_admin(KN_NETDP netdp, int opcode, const char *instr, int inlen, const char **outbuf, int buflen); Description is a network descriptor pointer, the KwikNet handle used to identify the network interface of interest.
Description ...continued Interpretation of parameters instr and outbuf for each value of opcode is as follows. For operation codes KN_PPPAUTH_LPNAME, KN_PPPAUTH_LCNAME and KN_PPPAUTH_LECNAME, instr and buflen are unused. A pointer to the local name for the specified authentication protocol is stored at *outbuf. Note that CHAP and MS-CHAP share a common local name. Hence, if MS-CHAP is used but CHAP is not used, this function must provide the CHAP local name when requested.
...continued Returns For operations which return a pointer to an authentication parameter in the storage at *outbuf, an integer n is returned. The value of n reflects the success or failure of the request. n >= 0 n = -1 Length of the authentication parameter referenced by the character pointer stored at *outbuf Authentication parameter is not available For operation code KN_PPPAUTH_PPCHECK, an integer n is returned which reflects the success or failure of the validity check requested.
6.5 Adding PPP to Your Application Before you add the PPP protocol to your application, you must have a working KwikNet IP stack (with or without TCP) operating with your RT/OS and your serial device driver. It is imperative that you start with a tested TCP/IP stack with functioning device drivers before you add PPP. If these components are not operational, the KwikNet PPP option cannot operate correctly. KwikNet Library Begin by deciding which PPP features must be supported.
Reconstructing Your KwikNet Application If you have not already done so, add your network serial device drivers to your application. Start by reviewing your KwikNet board driver module KN_BOARD.C. Unless you have modified the board driver, it supports four network interrupt sources. If necessary, increase the number of supported network interrupt sources to allow support for your network serial device drivers.
7. KwikNet Virtual File System 7.1 Introduction For embedded systems which may not need a full-featured file system, KwikNet offers a Virtual File System (VFS) which can provide access to a limited set of read-only files built into the application. A virtual file is a duplicate of a real disk file which you have on your development system. However, the virtual file does not reside on a disk. Instead, it sits in the memory of your target system.
VFS File Names The file name of a virtual file is a text string consisting of two parts, the volume base and the file part, separated by the / or \ character. The volume base is a string which will only be used by the Virtual File System when your application is running. Its main purpose is to allow you to distinguish your virtual files from real files. If you are not using a real file system, the volume base can be omitted. The volume base is common to all files in a VFS volume.
VFS File Operations The Virtual File System provides a set of file access functions with names of the form kvf_xxxxx(). These functions, listed in Figure 7.1-1, are described in detail in Chapter 7.5. Function prototypes are located in header file KN_FILES.H in the KwikNet TCPIP installation directory. Your application can use these functions to access virtual files or real files.
VFS File Access Rights User access to files within the KwikNet Virtual File System is governed by the KwikNet Administration Interface as described in Appendix D. The access rules are the same for all file systems. Each user is identified with a user name and password and is given specific access rights. Each user can also be assigned a base directory with the user's access restricted to only those files contained within that base directory and its subdirectories.
7.2 Virtual File System Definition Each KwikNet Virtual File System volume is defined by directives contained in a text file called a VFS Definition File (VDF). A typical VFS Definition File is illustrated in Figure 7.2-1. The directives can be recognized as strings of the form ...XXXXXXX beginning in column one and followed by zero or more parameters. Any line of text which is not a valid directive is treated as a comment and is ignored.
A variation of the example from Figure 7.2-1 will illustrate how easy it is to reorganize files within a Virtual File System. The VFS Definition File shown in Figure 7.2-2 defines a Virtual File System with all files located in the VFS volume's base directory. Note that the same source files used in Figure 7.2-1 are used again. This example introduces several new features. It shows that the ...
File Compression The VFS Generator can compress the files which make up your Virtual File System, thereby reducing the memory required for your VFS image. The compression is done using a simple text string replacement algorithm. This technique has been adopted because the run-time file expansion is simple and fast. It is also especially suitable for HTML files which contain frequently repeated HTML tags.
VFS Definition File Directives Each directive in a VFS Definition File consists of a keyword of the form ...XXXXXX in column one followed by zero or more parameters which you must provide. In the examples which follow, symbolic names are used to represent parameters. When you create a VFS Definition File, you must replace the symbolic name with your particular parameter. Volume Base The VFS volume base which forms the initial part of every virtual file name must be defined using keyword ...BASEDIR. ...
Source Files The files which are to be inserted into your Virtual File System are specified using keyword ...IN. ...IN FILE,COMPRESS Parameter FILE is the name of a file to be included in your Virtual File System. The file must be located in a directory which is accessible from the directory specified by the ...SRCPATH directive. The file name specified by parameter FILE can include a relative path. Absolute paths or root relative paths are not allowed.
Compression Mode The VFS Generator operates with file compression enabled or disabled. The current compression state is referred to as the compression mode. By default, compression is enabled. All files are compressed as they are inserted into your Virtual File System. This default behavior can be altered using a VFS Generator command line switch as described in Chapter 7.3. The ...COMPRESS keyword can be used to change the VFS Generator's compression mode. ...
Tag String Case Adjustment The ...TAGCASE keyword is used to adjust the case of all compression strings defined using the ...TAG keyword. The ...TAGCASE feature allows strings defined using any case, including mixed case, to be easily converted to upper or lower case without having to edit the strings. ...TAGCASE USECASE If parameter USECASE is the word UPPER or LOWER, any compression string defined using the ...
Sector Size Virtual files are stored in character arrays which, for lack of a better term, are called sector arrays. By default, the maximum size of a sector array is 32,768 bytes. The ...SSIZE keyword can be used to change the maximum size of these sector arrays. ...SSIZE NBYTES Parameter NBYTES defines the maximum number of bytes which the VFS Generator will insert into a sector array. The upper limit for this parameter is 32,768 bytes.
7.3 Using the VFS Generator The KwikNet VFS Generator is a utility program which will create a Virtual File System for use with the KwikNet TCP/IP Stack. The VFS Generator is provided ready for use on a PC or compatible running the Microsoft® MS-DOS® or Windows® operating system. When KwikNet is installed on your hard disk, the VFS Generator utility program and its related files are stored in directory VFSGEN in your KwikNet installation directory. File KN_VFG.EXE KN_VFG.CT KN_VFG.
VFS Definition File YOUR_VFS.UVF VFS String File KN_VFG.UVF VFS Source File(s) *.HTM, *.GIF, etc. Virtual File System Generator VFS Template File KN_VFG.CT VFS Data File(s) YOURVFS*.C Figure 7.
Running the VFS Generator The KwikNet VFS Generator is a utility program which is provided ready for use on a PC or compatible running the Microsoft® MS-DOS® or Windows® operating system. The VFS Generator must be started from the MS-DOS command line or from the Windows MS-DOS command prompt. It can also be started from the Windows Run... dialog box. Alternatively, you can create a Windows shortcut to the VFS Generator's filename and then simply double click the shortcut's icon.
-p srcpath is the full path defining the location of VFS source files which are to be placed into the Virtual File System being generated. The working directory is used if a relative path is specified. The working directory is used if this option is omitted. You can use the ...SRCPATH directive in your definition file to override either the default or the srcpath path specification. Srcpath is the full path and file name of your VFS String File.
is the full path and file name of the KwikNet VFS Template File. The working directory is used if no path, or a relative path, is specified. By default, the VFS Template File KN_VFG.CT delivered with KwikNet will be used, provided that it can be found in the directory containing the VFS Generator utility program being executed. This option, if used, overrides the equivalent parameter, if any, specified in your definition file using the ...TEMPLATE directive.
Compiling the VFS Data Files The VFS Generator produces a set of one or more VFS Data Files which, collectively, form your Virtual File System. These data files are C source files which must be compiled to create your VFS object modules. If you wish, you can combine these VFS object modules into a VFS library module using your object module librarian. Either the VFS object modules or your VFS library module must be linked with your KwikNet application.
7.4 Multiple VFS Volumes The KwikNet Virtual File System usually consists of only one volume. However, the Virtual File System can be extended to include additional volumes. In fact, since virtual files cannot be dynamically created, adding a volume is the only way that a virtual file can be added to the file system at run time. Do not be fooled by the fact that one volume can be represented by several VFS Data Files.
7.5 VFS Service Procedures The following list summarizes KwikNet VFS service procedures which are accessible to your application. These procedures are all present in the KwikNet Library. They are grouped functionally for easy reference.
kvf_close kvf_close Purpose Close a Virtual File Used by n Setup Prototype is in file KN_FILES.H. #include "KN_LIB.H" #include "KN_FILES.H" int kvf_close(KN_VFILE *vfd); Description Vfd Returns If successful, a value of 0 is returned and the file is closed. Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a virtual file descriptor identifying the virtual file to be closed. On failure, a value of -1 is returned.
kvf_fsize kvf_fsize Purpose Fetch the Size of a Virtual File Used by n Setup Prototype is in file KN_FILES.H. #include "KN_LIB.H" #include "KN_FILES.H" long kvf_fsize(const char *name); Description Name Returns If successful, a value of n is returned where n is the size of the virtual file measured in bytes. If the virtual file has been compressed, the return value n is the size of the expanded file. Note that a virtual file can be of length 0.
kvf_isvfile kvf_isvfile Purpose Determine if a File is a Virtual File Used by n Setup Prototype is in file KN_FILES.H. #include "KN_LIB.H" #include "KN_FILES.H" int kvf_isvfile(const char *name); Description Name Returns A non-zero value is returned if the file specified by name is a virtual file. Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a filepath string providing the full path and file name of the virtual file of interest.
kvf_open kvf_open Purpose Open a Virtual File Used by n Setup Prototype is in file KN_FILES.H. #include "KN_LIB.H" #include "KN_FILES.H" KN_VFILE *kvf_open(const char *name, const char *mode); Description Name Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a filepath string providing the full path and file name of the virtual file to be opened. A virtual filename must begin with the volume base assigned to a Virtual File System volume.
kvf_read kvf_read Purpose Read from a Virtual File Used by n Setup Prototype is in file KN_FILES.H. #include "KN_LIB.H" #include "KN_FILES.H" size_t kvf_read(void *buf, size_t size, size_t cnt, KN_VFILE *vfd); Description Buf Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a pointer to storage for the data items to be read from the file. Size is the size in bytes of each item which is to be read from the file. Cnt is the number of items to be read from the file.
kvf_seek kvf_seek Purpose Seek Within a Virtual File Used by n Setup Prototype is in file KN_FILES.H. #include "KN_LIB.H" #include "KN_FILES.H" int kvf_seek(KN_VFILE *vfd, long offset, int mode); Description Vfd Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a virtual file descriptor identifying a currently open virtual file. is the displacement from the origin specified by parameter mode to which the virtual file's data pointer is to be set.
kvf_tell kvf_tell Purpose Determine the Current Position of the File Pointer in a Virtual File Used by n Setup Prototype is in file KN_FILES.H. #include "KN_LIB.H" #include "KN_FILES.H" long kvf_tell(KN_VFILE *vfd; Description Vfd Returns If successful, a value of n is returned where n is the position of the file pointer within the virtual file. If the file pointer is at the end of the file, the value n will be the number of bytes in the file.
kvf_voladd kvf_voldel kvf_voladd kvf_voldel Purpose Add/Delete a Virtual File System Volume Used by n Setup Prototype is in file KN_FILES.H. #include "KN_LIB.H" #include "KN_FILES.H" int kvf_voladd(const struct knx_vfsvol *volume); int kvf_voldel(const struct knx_vfsvol *volume); Description Volume Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is pointer to a VFS volume description created by the VFS Generator.
A. Reference Materials and Glossary A.1 Reference Materials The following reference books and documents are recommended by KADAK's technical staff as good sources of information about TCP/IP and related protocols. Comer's text provides interesting historical background and a good general introduction to the topics of interest. Siyan's massive document is an excellent TCP/IP handbook. Books CARLSON, James [1998], PPP Design and Debugging, Addison Wesley Longman, Inc., Reading, Massachusets.
This page left blank intentionally.
A.2 KwikNet Glossary API App-Task An application programming interface defines the method by which a software program can access software components such as procedures in the KwikNet Library. The name given to the body of application code which uses services in a single threaded system. The App-Task is any application function (except those executed by an interrupt service routine) which calls KwikNet to perform some operation.
Handle An identifier assigned by AMX or KwikNet for use by your application to reference a private AMX or KwikNet data item. ICMP Internet Control Message Protocol: a component of the IP protocol which handles error and control messages. Interrupt Handler An application procedure called from an ISR or ISP root to service an interrupting device. Interrupt Service Procedure (ISP) A procedure (in an AMX application) which is executed in response to an external device interrupt request.
MAC Media Access Control: a general term used to define the method by which access to a physical network is controlled. This term is sometimes used when referencing Ethernet cards since Ethernet is a very common MAC protocol. Memory Block A portion of a memory pool that has been allocated for use by one or more tasks. Memory Pool A collection of memory sections whose use is controlled by the AMX Memory Manager.
A-6 RAM Alterable memory used for data storage and stacks. Restart Procedure An AMX or application procedure executed by AMX during the initialization phase when an AMX system is started. ROM Read only memory of all types including PROMs, EPROMs and EAROMs. RTOS A short form for referencing a real-time operating system, usually one with multitasking capability and reasonably good response to rapidly occurring external events.
System Configuration Module A software module, produced by the AMX Configuration Builder, which defines the characteristics of a particular AMX application. System Tick A multiple of the hardware clock tick from which the fundamental unit of time for an RT/OS is derived. All time intervals in the system are measured in multiples of the system tick. Tag A 4-character name that can be assigned to any AMX system data structure when it is created.
This page left blank intentionally.
B. KwikNet Error Codes TCP/IP Socket Error Codes TCP/IP socket error codes are signed integers. An error code of -1 indicates that a socket error has occurred. Codes greater than zero describe the reason for the error. To assist you during testing, the hexadecimal value of the least significant 16-bits of the error code is listed as it might appear in a register or memory dump.
KwikNet Error Codes error codes are signed integers. Codes less than zero are error codes. Codes greater than zero are warning codes. To assist you during testing, the hexadecimal value of the least significant 16-bits of the error code is listed as it might appear in a register or memory dump.
KwikNet Error Codes (continued) Mnemonic Value Value (dec) (hex) Meaning TFTP errors KN_ERTFD -260 KN_ERTFNOCONN -261 KN_ERTFEOF -262 KN_ERTFPROTO -263 KN_ERTFUDP -264 KN_ERTFWOULDBLOCK -265 KN_ERTFTRUNC -266 KN_ERTFDTYPE -267 KN_ERTFSTATE -268 KN_ERTFTIMEOUT -269 KN_ERTFNOPORT -270 0xFEFC 0xFEFB 0xFEFA 0xFEF9 0xFEF8 0xFEF7 0xFEF6 0xFEF5 0xFEF4 0xFEF3 0xFEF2 Invalid TFTP descriptor Not connected Not at end of file TFTP error packet was sent or received Unknown UDP error Operation would have blocked D
KwikNet Error Codes (continued) Mnemonic Value Value (dec) (hex) Meaning SMTP errors KN_ERSMND KN_ERSMSOCK KN_ERSMNET KN_ERSMNOCONN KN_ERSMNOSESS KN_ERSMINSESS KN_ERSMACTIVE KN_ERSMFAIL KN_ERSMMODE KN_ERSMNOLOG KN_ERSMREFUSE KN_ERSMREJECT KN_ERSMSEQ KN_ERSMSIZE KN_ERSMTM_DATA KN_ERSMTM_SEND KN_ERSMTM_EOM KN_ERSMTMCONN KN_ERSMTMREPLY B-4 -280 -281 -282 -283 -284 -285 -286 -287 -288 -289 -290 -291 -292 -293 -294 -295 -296 -297 -298 0xFEE8 0xFEE7 0xFEE6 0xFEE5 0xFEE4 0xFEE3 0xFEE2 0xFEE1 0xFEE0 0xFEDF
KwikNet Fatal Error Codes Mnemonic Value Value (dec) (hex) Meaning KN_FERNOTASK KN_FERNOTMR 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 Cannot find KwikNet Task Cannot create network timer reserved reserved Cannot send fn msg to KwikNet Task reserved Cannot send event msg to KwikNet Task Cannot suspend a task to wait for event Cannot resume a task after event occurs reserved No semaphores available for use reserved Resource lock failed Resource unlock failed No
This page left blank intentionally.
C. KwikNet File System Interface C.1 Introduction The KwikNet TCP/IP Stack does not require a file system for normal use. However, several of the optional KwikNet components, such as the FTP client and server and the HTTP Web Server, do require file services. For these options, KwikNet offers a variety of file system solutions, all of which are accessed through the Treck file system application programming interface (API) which is documented in Chapter 6 of the Treck TCP/IP Stack User Manual. C.1.
C.1.2 KwikNet Universal File System provides an alternate interface to the file services provided by the file system operating on the target platform. The KwikNet Universal File System (UFS) interface maps the Treck file system API to equivalent UFS services. The UFS can also be used concurrently with the KwikNet Virtual File System described in Chapter 7.
C.2 KwikNet File System Parameters The KwikNet Universal File System (UFS) interface and the Treck File System variants are included as components in the KwikNet Library. To include the UFS or Treck file system in the library, you must use the KwikNet Configuration Builder to edit your KwikNet Network Parameter File. The file system parameters are edited using the File System property page. The layout of the window is shown below.
File System Parameters (continued) Attached File System If you are using a KwikNet option such as FTP or HTTP which requires a file system, choose the file system you will be using with KwikNet. From the pull down list, select the underlying file system which you intend to use. Choose AMX/FS, "Standard C (MS-DOS)" or "User defined" if you are using a file system which is accessed via the KwikNet Universal File System API.
File System Parameters (continued) Maximum Path and File Name Lengths Specify the maximum number of characters which can appear in a path name string used to reference a directory location. The path length must include room for a terminating '\0' character. The path length excludes any file name. Specify the maximum number of characters which can appear in a file name string used to identify any file. The file name includes the base name and extension(s) and any separating characters.
C.3 Using the AMX/FS File System The KwikNet Universal File System (UFS) interface supports the AMX/FS File System. No customization is required. Any file devices, including RAM drives, hard drives, floppy drives and custom devices, which have been attached to the AMX/FS File System are accessible through the UFS interface. To use the AMX/FS File System with KwikNet, you must first install AMX and AMX/FS and test them in your intended target environment.
AMX System Startup Special care must be taken when launching an AMX system which includes both KwikNet and the AMX/FS File System. Initialize AMX/FS before starting KwikNet. This implies that execution of AMX/FS Restart Procedure fj_restart() must precede the call to KwikNet function kn_enter(). AMX/FS requires that a logical drive be mounted before it can be accessed. This operation is not supported by the Universal File System interface.
C.4 Using the MS-DOS File System When used with AMX 86, the KwikNet Universal File System (UFS) interface supports the MS-DOS® file system. No customization is required. All file devices, including RAM drives, hard drives and floppy drives, are accessible through the UFS interface. AMX 86 includes a component called the PC Supervisor which permits AMX 86 to be used with MS-DOS on PC platforms. Special care must be taken when using the PC Supervisor with AMX and KwikNet as described in Chapter 3.7.1.
C.5 Using a Custom File System The KwikNet Universal File System (UFS) interface can be adapted to support a custom file system. To do so, you need only edit file KNFSUSER.H to meet the requirements of your custom file system. No other customization is required. Once file KNFSUSER.H is ready, simply edit the File System parameters in your KwikNet Network Parameter File to reference your custom file system. Then build your KwikNet Library and link it with your application.
This page left blank intentionally.
D. KwikNet Administration Interface D.1 Introduction Many network protocols, such as FTP, were originally developed when large mainframe computers were shared by many users. The computers accommodated multiple users, each with a password and all administered by a higher authority. Network protocols were developed to support user names and passwords. Unfortunately, user name and password administration services are rarely provided by the operating systems found in desktop computers or embedded devices.
User Access Rights User access rights are formed from the logical OR of the following bit masks which are defined in header file KN_ADMIN.H.
D.2 KwikNet Administration Parameters The KwikNet administration interface forms part of the KwikNet Library. To adapt the administration interface parameters for your use, you must use the KwikNet Configuration Builder to edit your KwikNet Network Parameter File. The administration parameters are edited using the File System property page. The layout of the window is shown below.
Administration Parameters (continued) Maximum User Name and Password Lengths Specify the maximum number of characters which can appear in a user name string. The user name length must include room for a terminating '\0' character. Specify the maximum number of characters which can appear in a user password string. The password length must include room for a terminating '\0' character. For most applications, a user name length of 32 and a password length of 24 will be adequate.
E. KwikNet Sample Program Architecture The manner in which the KwikNet TCP/IP Sample Program starts and operates is completely dependent upon the underlying operating system with which KwikNet is being used. Operation can be either multitasking or single threaded. All sample programs provided with KwikNet and its optional components share the common implementation methodology about to be described. All KwikNet sample programs are built upon a common framework.
KNSAMOS.C Application OS Interface main() Sample program main entry point sam_osshutdown() OS shutdown on exit sam_ostkprep() Task create/prepare sam_ostkstart() Task start sam_record() Log function used by kn_dprintf() Print task print_task() backg_task() Background task (AMX only) rrproc() Restart Procedure (AMX only) exproc() Exit Procedure (AMX only) KNRECORD.
KwikNet Sample Program Operation with AMX When KwikNet is used with AMX, the KwikNet sample programs operate as follows. Once your board level initialization is complete and the C startup code has been executed, the sample program begins execution at main() in the Application OS Interface module KNSAMOS.C. The main program makes a series of calls to initialize the various components which make up the sample program.
The sample program begins operation at task level once AMX completes its startup processing. The client task executes and calls function app_enter(), the entry point to the main body of the sample program. The client task starts KwikNet with a call to KwikNet procedure kn_enter(). KwikNet initializes all of its private resources and starts the KwikNet Task which prepares all network interfaces and their associated device drivers for use.
KwikNet Porting Kit Sample Program - Multitasking Operation When the KwikNet Porting Kit is used with a multitasking RTOS, the KwikNet sample programs operate as follows. Once your board level initialization is complete and the C startup code has been executed, the sample program begins execution at main() in the Application OS Interface module KNSAMOS.C. The main program makes a series of calls to initialize the various components which make up the sample program.
The sample program begins operation at task level once the high priority startup task terminates. The client task executes and calls function app_enter(), the entry point to the main body of the sample program. The client task starts KwikNet with a call to KwikNet procedure kn_enter(). KwikNet initializes all of its private resources and starts the KwikNet Task which prepares all network interfaces and their associated device drivers for use.
KwikNet Porting Kit Sample Program - Single Threaded Operation When the KwikNet Porting Kit is used with a single threaded operating system (OS), the KwikNet sample programs operate as follows. Once your board level initialization is complete and the C startup code has been executed, the sample program begins execution at main() in the Application OS Interface module KNSAMOS.C. The main program makes a series of calls to initialize the various components which make up the sample program.
This page left blank intentionally.
